Java HTTP 集成

Telemetry 不发布本机 Java SDK。当 Java 或 JVM 服务需要结构化事件摄取或 SQL 查询时，通过一个应用程序拥有的 java.net.http.HttpClient 使用 HTTP API。

此边界将连接重用、超时、重试、序列化和故障策略保持在服务的控制之下。

创建一个共享客户端

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();

在应用程序启动期间创建一次客户端。使用服务器端写入范围的 API 密钥进行摄取，使用单独的读取范围的密钥进行报告或查询自动化。

发送一个结构化事件

使用应用程序已批准的 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

使用读取范围的密钥将包含 query 的 JSON 正文发布到 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、速率限制和错误 和 事件传递和幂等性。