Tulis Data Time Series melalui Objek Point SDK TSDB - Time Series Database - Alibaba Cloud -

Time Series Database (TSDB) Java SDK menggunakan kelas Point untuk merepresentasikan satu titik data. Untuk menulis data, buat satu atau beberapa objek Point, lalu kirimkan menggunakan mode asinkron atau sinkron.

Buat objek Point

Point memerlukan nama metrik, setidaknya satu pasangan kunci-nilai tag, sebuah nilai, dan stempel waktu. TSDB mendukung tiga format stempel waktu.

Skema data yang digunakan dalam contoh di bawah ini:

Field	Tipe	Deskripsi
`metric`	string	Nama pengukuran, misalnya `test1`
`tagk1`	tag	Contoh kunci tag 1
`tagk2`	tag	Contoh kunci tag 2
`tagk3`	tag	Contoh kunci tag 3
`value`	double	Nilai yang diukur
`timestamp`	long atau Date	Titik waktu pengukuran

Penting

Setiap Point harus menyertakan setidaknya satu pasangan kunci-nilai tag.

Stempel waktu dalam detik

// Konversi milidetik ke detik.
int timestamp = (int)(System.currentTimeMillis() / 1000);

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .tag("tagk2", "tagv2")
                   .tag("tagk3", "tagv3")
                   .timestamp(timestamp).value(123.456)
                   .build();

Stempel waktu dalam milidetik dengan HashMap

Gunakan HashMap untuk mengirimkan beberapa tag ketika jumlah tag bersifat dinamis atau besar.

long timestamp = System.currentTimeMillis();

Map<String, String> tags = new HashMap<String, String>();
tags.put("tagk1", "tagv1");
tags.put("tagk2", "tagv2");

Point point = Point.metric("test1")
                   .tag(tags)
                   .value(timestamp, 123.456)
                   .build();

java.util.Date

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(new Date(), 123.456)
                   .build();

Pilih mode penulisan

TSDB mendukung dua mode penulisan:

Mode	Metode	Batching	Paling cocok untuk
Asinkron (direkomendasikan)	`tsdb.put(point)`	Otomatis	Sebagian besar kasus penggunaan
Sinkron	`tsdb.putSync(points)`	Manual	Ketika Anda perlu memeriksa hasil penulisan secara langsung

Gunakan mode asinkron kecuali Anda memiliki alasan spesifik untuk memeriksa hasil per batch secara sinkron.

Tulis data secara asinkron

Dalam mode asinkron, buat objek Point dan panggil tsdb.put(). Klien secara otomatis mengelompokkan titik data sebelum mengirimkannya.

Point point = Point.metric("test1")
                   .tag("tagk1", "tagv1")
                   .value(timestamp, Math.random())
                   .build();

tsdb.put(point);

Konfigurasikan antarmuka callback

Untuk memeriksa hasil penulisan dalam mode asinkron, konfigurasikan antarmuka callback sebelum melakukan koneksi. Callback tersebut melacak keberhasilan dan kegagalan per batch.

Semua contoh di bawah ini menggunakan model data nilai tunggal. Untuk titik data multi-nilai, ganti antarmuka callback dengan varian MultiField yang sesuai (lihat Antarmuka callback).

final AtomicLong processedCount = new AtomicLong();

BatchPutCallback cb = new BatchPutCallback() {

    @Override
    public void response(String address, List<Point> input, Result output) {
        long total = processedCount.addAndGet(input.size());
        System.out.println("Ditulis: " + input.size() + ", total diproses: " + total);
    }

    @Override
    public void failed(String address, List<Point> input, Exception ex) {
        ex.printStackTrace();
        long total = processedCount.addAndGet(input.size());
        System.out.println("Gagal: " + input.size() + ", total diproses: " + total);
    }
};

TSDBConfig config = TSDBConfig
                        .address("example.hitsdb.com", 8242)
                        .listenBatchPut(cb)    // Daftarkan callback.
                        .config();

tsdb = TSDBClientFactory.connect(config);

Kapan masing-masing metode callback dipicu:

Metode	Dipicu saat
`response()`	Server menerima dan memproses permintaan. Konten respons bervariasi tergantung jenis callback.
`failed()`	Server menolak permintaan — data tidak valid, pembatasan kecepatan trafik, kegagalan otentikasi, atau error lainnya.

Penting

Selalu implementasikan metode failed(). Implementasi default-nya adalah metode void tanpa operasi, sehingga kegagalan akan diabaikan secara diam-diam jika Anda tidak mengimplementasikannya.

Penting

Jangan menjalankan operasi yang memakan waktu lama di dalam metode callback. Pindahkan pekerjaan berat ke thread pekerja terpisah.

Antarmuka callback

Pilih antarmuka callback yang sesuai dengan tingkat detail respons penulisan yang Anda butuhkan.

Model data nilai tunggal:

Antarmuka callback	Mode penulisan	API ekuivalen
`BatchPutCallback`	Sederhana	`POST /api/put`
`BatchPutSummaryCallback`	Statistik	`POST /api/put?summary=true`
`BatchPutDetailsCallback`	Detail	`POST /api/put?details=true`
`BatchPutIgnoreErrorsCallback`	Toleransi kesalahan	`POST /api/put?ignoreErrors=true`

Model data multi-nilai:

Antarmuka callback	Mode penulisan	API ekuivalen
`MultiFieldbatchPutCallback`	Sederhana	`POST /api/put`
`MultiFieldbatchPutSummaryCallback`	Statistik	`POST /api/put?summary=true`
`MultiFieldbatchPutDetailsCallback`	Rinci	`POST /api/put?details=true`
`MultiFieldbatchPutIgnoreErrorsCallback`	Toleransi kesalahan	`POST /api/put?ignoreErrors=true`

Untuk detail konten respons tiap mode penulisan, lihat Mode dan respons penulisan.

Tulis data secara sinkron

Dalam mode sinkron, buat daftar titik data secara manual dan panggil tsdb.putSync().

List<Point> points = new ArrayList<Point>();

for (int i = 0; i < 500; i++) {
    long timestamp = System.currentTimeMillis();
    Point point = Point.metric("test1")
                       .tag("tagk1", "tagv1")
                       .value(timestamp, Math.random())
                       .build();
    points.add(point);
}

tsdb.putSync(points);

Praktik terbaik untuk penulisan sinkron

Tambahkan 500–1.000 titik data per batch. Jumlah titik yang lebih sedikit per pemanggilan mengurangi throughput; terlalu banyak meningkatkan tekanan memori.
Kirimkan batch dari beberapa thread secara konkuren untuk memaksimalkan throughput penulisan.

Tipe respons sinkron

Konfigurasikan tipe respons berdasarkan apa yang perlu diverifikasi aplikasi Anda setelah setiap penulisan.

Tipe respons	Kode	API ekuivalen	Konten
Objek kosong	`Result result = tsdb.putSync(ps);`	`POST /api/put`	Tanpa muatan
Ringkasan	`SummaryResult summaryResult = tsdb.putSync(ps, SummaryResult.class);`	`POST /api/put?summary=true`	Jumlah ditulis, jumlah gagal
Detail	`DetailsResult detailsResult = tsdb.putSync(ps, DetailsResult.class);`	`POST /api/put?details=true`	Jumlah ditulis, jumlah gagal, alasan kegagalan