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 リクエスト本文から組み立てられたのではなく、許可リストに登録されたオブジェクトからシリアル化されました。

アプリケーションの結果が確定してから送信します。正規化した実際の routeTemplate、requestMethod、数値の statusCode と latencyMs を使い、架空の成功ステータスを本番環境にコピーしないでください。Map.of の値はすべて非 null にします。以下はタイムアウトを設定したベストエフォート送信です。配信とシリアライズの失敗を捕捉し、スレッドの割り込み状態を保持します。再試行も保存の保証もしません。ローカル診断にキー、レスポンス本文、例外メッセージは含めません。

診断出力の非検査例外も捕捉します。送信は同期的に実行されるため、アプリケーション処理のレイテンシが増える場合があります。

java.util.function.Consumer<String> deliveryDiagnostic = message -> {
    try {
        System.err.println(message);
    } catch (RuntimeException diagnosticFailure) {
        // Diagnostics must not replace the application outcome.
    }
};

try {
    String eventJson = objectMapper.writeValueAsString(Map.of(
        "table", "api_request_completed",
        "data", Map.of(
            "event_id", eventId,
            "route_template", routeTemplate,
            "method", requestMethod,
            "status_code", statusCode,
            "status", statusCode >= 500 ? "failed" : "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<Void> response = telemetryHttp.send(
        request,
        HttpResponse.BodyHandlers.discarding()
    );

    if (response.statusCode() < 200 || response.statusCode() >= 300) {
        deliveryDiagnostic.accept("Telemetry delivery failed (non-2xx response).");
    }
} catch (InterruptedException error) {
    Thread.currentThread().interrupt();
    deliveryDiagnostic.accept("Telemetry delivery interrupted.");
} catch (java.io.IOException | RuntimeException error) {
    deliveryDiagnostic.accept("Telemetry delivery failed (transport, serialization or configuration error).");
}

ルートテンプレートと値を制限したエラーカテゴリを使用してください.ヘッダー、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
FROM api_request_completed
ORDER BY timestamp_utc DESC
LIMIT 20;

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

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