Integración de Java HTTP

Telemetry no publica un SDK nativo de Java. Utilice HTTP API a través de un java.net.http.HttpClient propiedad de la aplicación cuando un servicio Java o JVM necesite ingesta de eventos estructurados o consultas SQL.

Este límite mantiene la reutilización de la conexión, los tiempos de espera, los reintentos, la serialización y la política de fallas bajo el control del servicio.

Crear un cliente compartido

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

Cree el cliente una vez durante el inicio de la aplicación. Utilice una clave API de solo ingesta para la ingesta y una clave independiente con ámbito de lectura para informes o automatización de consultas.

Enviar un evento estructurado

Utilice la biblioteca JSON ya aprobada por la aplicación. Este ejemplo supone que eventJson se serializó a partir de un objeto incluido en la lista de permitidos en lugar de ensamblarse a partir de un cuerpo de solicitud:

Ejecuta este envío solo cuando se conozca el resultado de la aplicación. Usa los valores reales de routeTemplate normalizado, requestMethod, statusCode numérico y latencyMs; no copies un estado de éxito ficticio a producción. Ningún valor de Map.of puede ser nulo. El envío de mejor esfuerzo limita el tiempo, captura fallos de entrega y serialización, conserva la interrupción del hilo y no reintenta ni garantiza el almacenamiento. El diagnóstico local no incluye claves, cuerpos de respuesta ni texto de excepciones.

También se contienen los errores no comprobados del diagnóstico. El envío sigue siendo síncrono y puede añadir latencia a la aplicación.

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).");
}

Utilice plantillas de ruta y categorías de error controladas. No serialice encabezados, cookies, credenciales, cuerpos de solicitud, parámetros SQL, seguimientos de pila, mensajes, contenido generado ni mensajes de excepción sin restricciones.

Ejecute SQL

PUBLICAR un cuerpo JSON que contiene query en https://api.telemetry.sh/query con una clave de alcance de lectura:

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

Verifique el estado de HTTP y los campos de respuesta status, data y key_order. Trate un resultado vacío como un estado válido en lugar de un error de análisis.

Política de error y reintento

Reintente solo fallas transitorias limitadas, como errores de conexión, 429, 502, 503 y 504. Utilice un retroceso exponencial con fluctuación, limite el tiempo transcurrido y conserve el mismo event_id en todos los intentos. No vuelva a intentar respuestas 400, 401 o 403 sin cambios.

Para el análisis de productos ordinario, una falla de telemetría no debe reemplazar una respuesta completa del cliente. Si un evento de facturación o auditoría aprobado debe ser duradero, escriba un registro de la bandeja de salida en la misma transacción que el estado comercial y entréguelo de un trabajador.

Verificar la integración

Envíe accesorios controlados de éxito, error, reintento y tiempo de espera, luego inspeccione las filas recientes:

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

Confirme el grano del evento, el nombre de la tabla, los tipos de campo, las unidades, la hora UTC y el límite de privacidad. Pruebe un tiempo de espera de Telemetry y el cierre del proceso antes de poner la entrega en una ruta de alto tráfico.

Continúe con Integración de arranque de primavera, Registro API, límites de tasa y errores y entrega de eventos e idempotencia.

Usa esta documentación con tu agente de programación