Lewati ke isi

Pengembangan Skrip / Objek Konektor DFF.CONN / DataKit dan DataWay

Objek operasi dari Konektor DataKit dan DataWay terutama menyediakan metode penulisan data.

Parameter DFF.CONN(...) adalah sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
connector_id str Wajib ID Konektor
source str None Menimpa Source Konektor
Perhatikan: jangan mengisi nama collector seperti "mysql" agar tidak menimbulkan kebingungan
timeout int/float 10 Waktu tunggu default permintaan HTTP untuk objek operasi saat ini, dalam detik
split_size int 100 Jumlah titik data per permintaan saat melakukan penulisan batch line protocol
Parameter Tipe Wajib / Nilai Default Deskripsi
connector_id str Wajib ID Konektor
token str None Menimpa Token Konektor
timeout int/float 10 Waktu tunggu default permintaan HTTP untuk objek operasi saat ini, dalam detik
split_size int 100 Jumlah titik data per permintaan saat melakukan penulisan batch line protocol
  • Untuk pelaporan data umum, gunakan metode .write_by_category(...) dan .write_by_category_many(...)
  • Untuk menjalankan pernyataan DQL secara umum, gunakan metode .query(...)
  • Untuk mengirim permintaan GET secara langsung, gunakan metode .get(...)
  • Untuk mengirim permintaan POST secara langsung, gunakan metode .post_json(...)
  • Untuk mengirim data line protocol secara langsung, gunakan metode .post_line_protocol(...)

Konektor ini pada dasarnya adalah pembungkus dari permintaan HTTP

Sebagian besar antarmuka antara DataKit dan DataWay identik.

Karena antarmuka DataKit dan DataWay sering berubah, Konektor ini tidak membungkus semua antarmuka secara satu-ke-satu.

Karena versi DataKit dan DataWay yang berbeda dapat memiliki persyaratan atau batasan yang berbeda untuk data yang dilaporkan, gunakan Konektor ini setelah membaca dokumentasi terkait.

Lihat dokumentasi lengkap di:

.write_by_category(...)

Untuk menulis data dengan tipe tertentu ke DataKit dan DataWay, parameternya adalah sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
category str Wajib Tipe data, lihat Dokumentasi TrueWatch / DataKit API
measurement str Wajib Nama kumpulan metrik
tags dict None Tag. Nama kunci dan nilai kunci harus berupa string
fields dict Wajib Metrik. Nama kunci harus berupa string; nilai dapat berupa string, integer, float, boolean, atau daftar tipe-tipe tersebut dengan tipe elemen yang konsisten
timestamp int/long/float {waktu saat ini} Timestamp, mendukung detik/milidetik/mikrodetik/nanodetik
headers dict None Parameter Header permintaan
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi

Parameter headers ditambahkan pada 3.3.0

Contoh
1
2
3
tags   = { 'host': 'web-01' }
fields = { 'cpu' : 10 }
status_code, result = datakit.write_by_category(category='metric', measurement='Pemantauan Host', tags=tags, fields=fields)

.write_by_category_many(...)

Versi batch dari write_by_category(...), parameternya adalah sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
category str Wajib Tipe data, lihat Dokumentasi TrueWatch / DataKit API
data list Wajib Daftar titik data
data[#].measurement str Wajib Nama kumpulan metrik
data[#].tags dict None Tag. Nama kunci dan nilai kunci harus berupa string
data[#].fields dict Wajib Metrik. Nama kunci harus berupa string; nilai dapat berupa string, integer, float, boolean, atau daftar tipe-tipe tersebut dengan tipe elemen yang konsisten
data[#].timestamp int/long/float {waktu saat ini} Timestamp, mendukung detik/milidetik/mikrodetik/nanodetik
headers dict None Parameter Header permintaan
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi

Parameter headers ditambahkan pada 3.3.0

Contoh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
data = [
    {
        'measurement': 'Pemantauan Host',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': 'Pemantauan Host',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_by_category_many(category='metric', data=data)

.write_metric(...) / .write_point(...)

.write_metric(...) setara dengan .write_by_category(category='metric', ...); .write_point(...) adalah alias kompatibilitas versi lama.

Contoh
1
status_code, result = datakit.write_metric(measurement='Pemantauan Host', tags={'host': 'web-01'}, fields={'cpu': 10})

.write_metric_many(...) / .write_metrics(...) / .write_points(...)

.write_metric_many(...) setara dengan .write_by_category_many(category='metric', ...); .write_metrics(...) dan .write_points(...) adalah alias kompatibilitas versi lama.

Contoh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
data = [
    {
        'measurement': 'Pemantauan Host',
        'tags'       : { 'host' : 'web-01' },
        'fields'     : { 'value': 10 }
    },
    {
        'measurement': 'Pemantauan Host',
        'tags'       : { 'host' : 'web-02' },
        'fields'     : { 'value': 20 }
    }
]
status_code, result = datakit.write_metrics(data=data)

.write_logging(...) / .write_logging_many(...)

.write_logging(...) setara dengan .write_by_category(category='logging', ...); .write_logging_many(...) adalah versi batch yang sesuai.

.query(...)

Metode ini mendukung parameter dalam antarmuka kueri DQL API DataKit dan DataWay

Lihat dokumentasi lengkap di Dokumentasi TrueWatch / DataKit API

Metode ini hanyalah pembungkus permintaan HTTP

Metode ini pada dasarnya hanya mengirim permintaan HTTP ke DataKit dan DataWay; konten yang dikembalikan bergantung pada DataKit, DataWay, serta sumber data backend.

Jika ragu dengan hasil yang dikembalikan, Anda dapat mencoba menggunakan requests untuk mengirim permintaan langsung ke DataKit dan DataWay:

Menggunakan requests untuk memanggil antarmuka
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def query():
    domain = '<Domain>'
    token  = '<Token>'

    url = f'https://{domain}/v1/query/raw?token={token}'
    body = {
        'queries': [
            {
                # Pernyataan DQL
                'query': 'M::`cpu`:(`load5s`) BY `host`',

                # 1 jam terakhir
                'time_range': [
                    _DFF_TRIGGER_TIME_MS - 3600 * 1000,
                    _DFF_TRIGGER_TIME_MS,
                ],
            }
        ],
        'token': token
    }

    resp = requests.post(url, json=body)
    print(resp.status_code)
    print(resp.text)

Jalankan pernyataan DQL melalui DataKit dan DataWay, dengan parameter sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
dql str Wajib Pernyataan DQL
dict_output bool False Apakah data otomatis dikonversi menjadi dict.
raw bool False Apakah mengembalikan respons mentah. Setelah diaktifkan, parameter dict_output tidak berlaku.
all_series bool False Apakah otomatis melakukan paginasi melalui slimit dan soffset untuk mendapatkan semua timeline.
token str None Token ruang kerja yang hanya digunakan oleh DataKit; DataWay harus mengatur Token saat mendapatkan objek operasi
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi
{parameter native DataKit dan DataWay} - - Diteruskan ke queries[0].{parameter native DataKit dan DataWay}

Saat all_series diaktifkan, setiap halaman secara tetap meminta 500 timeline: kueri metrik dapat meminta paling banyak 20 halaman, sedangkan kueri lainnya paling banyak 5 halaman.

DataWay harus memiliki Token sebelum menjalankan kueri. Token harus diatur dalam konfigurasi Konektor atau DFF.CONN(..., token='...'); jangan meneruskan token berulang kali ke .query(...).

Contoh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # Menggunakan parameter native DataKit `time_range` untuk membatasi data 1 jam terakhir
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # Kueri dan kembalikan data sebagai dict
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', dict_output=True, time_range=time_range)
    print(json.dumps(result))
Contoh Output
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
  "series": [
    [
      {
        "time": 1622463105293,
        "host": "iZbp152ke14timzud0du15Z",
        "load": 2.18,
        "create_time": 1622429576363,
        "tags": {}
      },
      {
        "time": 1622462905921,
        "host": "ubuntu18-base",
        "load": 0.08,
        "create_time": 1622268259114,
        "tags": {}
      },
      {
        "time": 1622461264175,
        "host": "shenrongMacBook.local",
        "load": 2.395508,
        "create_time": 1622427320834,
        "tags": {}
      }
    ]
  ]
}
Contoh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
import time
import json

@DFF.API('Run DQL via DataKit')
def run_dql_via_datakit():
    datakit = DFF.CONN('datakit')

    # Tambahkan parameter raw untuk mendapatkan nilai mentah dari kueri DQL
    time_range = [
        int(time.time() - 3600) * 1000,
        int(time.time()) * 1000,
    ]

    # Kueri dan kembalikan data dalam format nilai balik mentah DataKit
    status_code, result = datakit.query(dql='O::HOST:(host,load,create_time)', raw=True, time_range=time_range)
    print(json.dumps(result, indent=2))
Contoh Output
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
{
  "content": [
    {
      "series": [
        {
          "name": "HOST",
          "columns": [
            "time",
            "host",
            "load",
            "create_time"
          ],
          "values": [
            [
              1622463165152,
              "iZbp152ke14timzud0du15Z",
              1.92,
              1622429576363
            ],
            [
              1622462905921,
              "ubuntu18-base",
              0.08,
              1622268259114
            ],
            [
              1622461264175,
              "shenrongMacBook.local",
              2.395508,
              1622427320834
            ]
          ]
        }
      ],
      "cost": "1ms",
      "total_hits": 3
    }
  ]
}

.get(...)

Metode ini adalah metode penanganan umum

Untuk format dan konten parameter secara spesifik, silakan lihat dokumentasi TrueWatch / DataKit API

Kirim permintaan GET ke DataKit dan DataWay, dengan parameter sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
path str Wajib Jalur permintaan
query dict None Parameter URL permintaan
headers dict None Parameter Header permintaan
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi

Mengembalikan (status_code, result). Jika isi respons dapat diurai sebagai JSON, result adalah objek terkait; jika tidak, berupa teks atau konten mentah.

.post_json(...)

Metode ini adalah metode penanganan umum

Untuk format dan konten parameter secara spesifik, silakan lihat dokumentasi TrueWatch / DataKit API

Kirim permintaan POST ke DataKit dan DataWay dalam format JSON, dengan parameter sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
path str Wajib Jalur permintaan
json_obj dict/list Wajib Objek JSON yang perlu dikirim
query dict None Parameter URL permintaan
headers dict None Parameter Header permintaan
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi

Parameter path telah diubah menjadi parameter pertama pada versi 1.6.8

Mengembalikan (status_code, result).

.post_line_protocol(...)

Metode ini adalah metode penanganan umum

Untuk format dan konten parameter secara spesifik, silakan lihat dokumentasi TrueWatch / DataKit API

Kirim permintaan POST ke DataKit dan DataWay dalam format line protocol, dengan parameter sebagai berikut:

Parameter Tipe Wajib / Nilai Default Deskripsi
path str Wajib Jalur permintaan
points dict/list Wajib Titik data tunggal atau daftar titik data
points[#].measurement str Wajib Nama kumpulan metrik
points[#].tags dict None Tag. Nama kunci dan nilai kunci harus berupa string
points[#].fields dict Wajib Metrik. Nama kunci harus berupa string; nilai dapat berupa string, integer, float, boolean, atau daftar dari tipe-tipe di atas yang elemennya bertipe sama
points[#].timestamp int/long/float {waktu saat ini} Stempel waktu, mendukung detik/milidetik/mikrodetik/nanodetik
query dict None Parameter URL permintaan
headers dict None Parameter Header permintaan
timeout int/float None Waktu timeout permintaan ini; jika dihilangkan, gunakan nilai default objek operasi

Parameter path telah diubah menjadi parameter pertama pada versi 1.6.8

Data batch dikirim dalam pecahan sesuai split_size. Metode ini mengembalikan (status_code, result) dari permintaan pecahan terakhir; jika salah satu permintaan pecahan gagal, pengecualian dilemparkan dan pengiriman selanjutnya dihentikan.