TSDB SDK Point オブジェクトによる時系列データの書き込み - Time Series Database - Alibaba Cloud -

TSDB SDK は、各データポイントを Point オブジェクトとして表します。Point は、時系列内の特定の時点における単一の測定値を記録します。

基本概念

各 Point オブジェクトには、次のフィールドが必要です：

フィールド	型	必須	説明	例
`metric`	String	はい	時系列の名前	`"cpu.usage"`
`tag`	Map	はい	時系列を識別する 1 つ以上のタグのキーと値のペア	`{"host": "web01"}`
`timestamp`	int / long / Date	はい	データポイントの時刻 (秒、ミリ秒、または `java.util.Date`)	`1711555200`
`value`	double	はい	測定値	`123.456`

Point オブジェクトの構築

TSDB SDK は、Point オブジェクトを構築する際にタイムスタンプを指定する 3 つの方法をサポートしています。

重要

すべての Point オブジェクトには、少なくとも 1 つのタグのキーと値のペアを含める必要があります。

秒単位のタイムスタンプ

// ミリ秒を秒に変換
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();

ミリ秒単位のタイムスタンプ

HashMap を使用して、複数のタグを一度に渡します：

long timestamp = System.currentTimeMillis();

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

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

java.util.Date

java.util.Date オブジェクトを value() メソッドに直接渡します：

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

データの書き込み

TSDB クライアントは、非同期と同期の 2 つの書き込みモードをサポートしています。アプリケーションで即時の書き込み確認が必要な場合を除き、非同期モードを使用してください。

非同期モード (推奨)

非同期モードでは、Point を構築して tsdb.put() を呼び出します。クライアントはデータポイントを送信する前に自動的にバッチ処理するため、手動でのリスト管理は不要です。

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

tsdb.put(point);

同期モード

同期モードでは、データポイントのリストを作成し、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);

応答の型は、アプリケーションが必要とする詳細レベルに応じて選択します：

応答の型	メソッド呼び出し	対応する API	戻り値
空のオブジェクト	`tsdb.putSync(ps)`	`POST /api/put`	空の結果オブジェクト
概要	`tsdb.putSync(ps, SummaryResult.class)`	`POST /api/put?summary=true`	成功した書き込みと失敗した書き込みの数
詳細	`tsdb.putSync(ps, DetailsResult.class)`	`POST /api/put?details=true`	成功した書き込みと失敗した書き込みの数、および各失敗の理由

非同期書き込みのコールバックの設定

非同期モードでサーバーの応答を検査するには、TSDBConfig を構築する際にコールバックを設定します。TSDB クライアントは、各書き込みモードに対応する 4 つのコールバックインターフェイスを提供します：

コールバックインターフェイス	書き込みモード	対応する API
`BatchPutCallback`	シンプル	`POST /api/put`
`BatchPutSummaryCallback`	統計	`POST /api/put?summary=true`
`BatchPutDetailsCallback`	詳細	`POST /api/put?details=true`
`BatchPutIgnoreErrorsCallback`	フォールトトレラント	`POST /api/put?ignoreErrors=true`

次の例では、BatchPutCallback を設定し、listenBatchPut() に登録します：

final AtomicLong num = new AtomicLong();

BatchPutCallback cb = new BatchPutCallback() {

    @Override
    public void response(String address, List<Point> input, Result output) {
        // サーバーがリクエストを受け入れて処理したときに呼び出されます
        long afterNum = num.addAndGet(input.size());
        System.out.println("Successful: " + input.size() + ", Processed: " + afterNum);
    }

    @Override
    public void failed(String address, List<Point> input, Exception ex) {
        // サーバーがリクエストを拒否したとき (速度制限、認証の失敗など) に呼び出されます
        ex.printStackTrace();
        long afterNum = num.addAndGet(input.size());
        System.out.println("Failed: " + input.size() + ", Processed: " + afterNum);
    }

};

TSDBConfig config = TSDBConfig
                        .address("example.hitsdb.com", 8242)
                        .listenBatchPut(cb)    // コールバックを登録
                        .config();

tsdb = TSDBClientFactory.connect(config);

コールバックメソッドの動作：

メソッド	呼び出されるタイミング
`response()`	サーバーがリクエストを受け入れて処理したとき。応答内容はコールバックの型によって異なります。
`failed()`	サーバーがリクエストを拒否したとき — 無効なメッセージ、速度制限、認証の失敗、またはその他のエラーが原因です。

重要

常に failed() を実装してください。これを省略すると、デフォルトの何もしない failed() メソッドが使用され、書き込みの失敗は警告なく無視されます。

重要

コールバックメソッド内で時間のかかる操作を実行しないでください。負荷の高い処理は、別のワーカースレッドにオフロードしてください。

複数値のデータポイントの場合は、各コールバックインターフェイスを、対応する複数フィールドのインターフェイスに置き換えます：

MultiFieldbatchPutCallback
MultiFieldbatchPutSummaryCallback
MultiFieldbatchPutDetailsCallback
MultiFieldbatchPutIgnoreErrorsCallback

書き込みモードとそれぞれの使用場面の詳細については、「書き込みモードと応答」をご参照ください。

ベストプラクティス

同期書き込みのバッチサイズ

tsdb.putSync() を呼び出す前に、リストごとに 500～1,000 のデータポイントを追加します。呼び出しあたりのポイント数が少なすぎるとネットワークオーバーヘッドが増加し、多すぎると呼び出しあたりのレイテンシーが増加する可能性があります。

同時実行性

複数のスレッドを使用して、データポイントのリストを同時に送信します。並列送信により、大容量のワークロードのスループットが大幅に向上します。