Java HTTP の統合

Telemetry は、ネイティブ Java SDK を公開しません。 1 つのアプリケーション所有を通じて HTTP API を使用する java.net.http.HttpClient Java または JVM サービスで構造化イベントの取り込みまたは SQL クエリが必要な場合。

この境界により、接続の再利用、タイムアウト、再試行、シリアル化、および失敗ポリシーがサービスの制御下に維持されます。

1 つの共有クライアントを作成する

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

HttpClient telemetryHttp = HttpClient.newBuilder()
    .connectTimeout(Duration.ofSeconds(2))
    .build();

アプリケーションの起動時にクライアントを 1 回作成します。取り込みにはサーバー側の書き込みスコープの API キーを使用し、レポートまたはクエリ自動化には別の読み取りスコープのキーを使用します。

1 つの構造化イベントを送信する

アプリケーションによって承認済みの JSON ライブラリを使用します。この例では次のことを前提としています eventJson リクエスト本文から組み立てられたのではなく、許可リストに登録されたオブジェクトからシリアル化されました。

String eventJson = objectMapper.writeValueAsString(Map.of(
    "table", "api_request_completed",
    "data", Map.of(
        "event_id", eventId,
        "route_template", "/api/projects/:id",
        "method", "POST",
        "status_code", 201,
        "status", "success",
        "latency_ms", latencyMs,
        "request_id", requestId,
        "release", release
    )
));

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telemetry.sh/log"))
    .timeout(Duration.ofSeconds(3))
    .header("Authorization", telemetryApiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(eventJson))
    .build();

HttpResponse<String> response = telemetryHttp.send(
    request,
    HttpResponse.BodyHandlers.ofString()
);

if (response.statusCode() < 200 || response.statusCode() >= 300) {
    recordDeliveryFailure(response.statusCode(), eventId);
}

ルートテンプレートと値を制限したエラーカテゴリを使用してください.ヘッダー、Cookie、資格情報、リクエスト本文、SQL パラメーター、スタック トレース、プロンプト、生成されたコンテンツ、または制限のない例外メッセージをシリアル化しないでください。

SQLを実行します

以下を含む JSON ボディを POST します。 query に https://api.telemetry.sh/query 読み取りスコープのキーを使用する場合:

String queryJson = objectMapper.writeValueAsString(Map.of(
    "query", """
        SELECT route_template, COUNT(*) AS requests
        FROM api_request_completed
        WHERE timestamp_utc >= now() - INTERVAL '24 hours'
        GROUP BY route_template
        ORDER BY requests DESC
        """
));

HttpRequest queryRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://api.telemetry.sh/query"))
    .timeout(Duration.ofSeconds(15))
    .header("Authorization", telemetryReadApiKey)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(queryJson))
    .build();

HTTPのステータスと応答を確認してください status, data、そして key_order フィールド。空の結果を解析失敗としてではなく、有効な状態として扱います。

失敗と再試行のポリシー

接続エラーなどの限定された一時的なエラーのみを再試行します。 429, 502, 503、そして 504。ジッターを伴う指数バックオフを使用し、経過時間を制限し、同じ時間を保持します event_id 試行全体にわたって。変更せずに再試行しないでください 400, 401、または 403 応答。

通常の製品分析では、テレメトリの失敗が完了した顧客応答に取って代わられるべきではありません。請求イベントまたは承認された監査イベントが永続的である必要がある場合は、ビジネス状態と同じトランザクションに送信トレイ レコードを書き込み、ワーカーから配信します。

統合を確認する

制御された成功、失敗、再試行、タイムアウト フィクスチャを送信し、最近の行を検査します。

SELECT timestamp_utc, event_id, route_template, status, latency_ms, error_type
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;

イベント粒度、テーブル名、フィールドタイプ、単位、UTC時間、プライバシー境界を確認します。トラフィックの多いパスに配信を配置する前に、Telemetry タイムアウトとプロセスのシャットダウンをテストします。

続けて、 Spring Bootの統合, ログ API, レート制限とエラー、そして イベント配信と冪等性.