SDK de Rust

La caja telemetry-sh proporciona un pequeño cliente de bloqueo para la ingesta de eventos y consultas interactivas. Cada método construye un cliente reqwest de bloqueo y envía una solicitud HTTP. La caja no expone un cliente asíncrono, un tiempo de espera configurable, una política de reintento, una cola por lotes ni un método de vaciado.

Instalar e inicializar

[dependencies]
telemetry-sh = "1.0.0"
serde_json = "1.0"
uuid = { version = "1", features = ["v4"] }

use std::env;
use telemetry_sh::Telemetry;

let mut telemetry = Telemetry::new();
telemetry.init(env::var("TELEMETRY_API_KEY")?);

Mantenga la clave en la configuración del lado del servidor. Utilice una clave con ámbito de escritura para servicios de solo ingesta y una clave con ámbito de lectura para informes o automatización de consultas.

Enviar un evento estructurado

use serde_json::json;
use uuid::Uuid;

let event_id = Uuid::new_v4().to_string();
let event = json!({
    "event_id": event_id,
    "job_name": "invoice_sync",
    "status": "success",
    "duration_ms": 912,
    "attempt": 1,
    "release": env::var("APP_RELEASE").ok(),
});

match telemetry.log("job_completed", &event) {
    Ok(response) => println!("telemetry response: {response}"),
    Err(error) => eprintln!(
        "telemetry delivery failed event_id={} error_type=transport_error: {}",
        event_id,
        error
    ),
}

Evite credenciales, encabezados, cookies, cuerpos de solicitud sin formato, mensajes, texto de excepción y contenido privado del cliente. Prefiere categorías controladas e identificadores internos estables.

El SDK acepta un serde_json::Value. Un valor de matriz puede representar una carga útil masiva de Log API, pero pruebe la caja exacta y el comportamiento de API antes de hacer que el procesamiento por lotes forme parte de un contrato de entrega de producción.

Ejecute SQL

let query = r#"
    SELECT
      status,
      COUNT(*) AS jobs
    FROM job_completed
    WHERE timestamp_utc >= now() - INTERVAL '24 hours'
    GROUP BY status
    ORDER BY jobs DESC
"#;

let result = telemetry.query(query)?;
let rows = result
    .get("data")
    .and_then(|value| value.as_array())
    .cloned()
    .unwrap_or_default();

println!("query rows: {}", rows.len());

El resultado es un JSON dinámico. Valide tipos, valores nulos, estado API y resultados vacíos antes de usar valores en la automatización. Utilice el Consulta asincrónica API directamente para exportaciones JSON o Parquet de larga duración.

Comportamiento de bloqueo y tiempo de espera

Ambos métodos de caja utilizan reqwest::blocking. No los llame directamente en un subproceso ejecutor asincrónico o en una ruta de solicitud sensible a la latencia sin aislar el trabajo de bloqueo.

La caja publicada no expone su cliente HTTP ni configura un tiempo de espera. Si el servicio necesita cancelación de contexto, reutilización de la conexión, un tiempo de espera fijo, reintentos de estado específico o una cola duradera, implemente la solicitud HTTP documentada con un reqwest::Client propiedad de la aplicación.

Mantenga la política de transporte limitada para que una interrupción de la telemetría no pueda agotar los subprocesos de los trabajadores.

Política de reintento y apagado

Reintente solo fallas de conexión transitorias, 429, 502, 503 y 504. Utilice un retroceso exponencial con fluctuación, limite el tiempo total y conserve el mismo event_id. No vuelva a intentar una solicitud no válida y sin cambios.

El SDK no tiene cola en segundo plano para vaciar. Una devolución exitosa de log significa que la solicitud inmediata produjo una respuesta descodificable; no es una promesa de almacenamiento exactamente una vez. Realice un seguimiento de las llamadas requeridas o persista eventos duraderos en una bandeja de salida propiedad de la aplicación antes de cerrar el proceso.

Para análisis ordinarios, no convierta una acción completada del cliente en una falla porque la telemetría no esté disponible. Revisar entrega de eventos e idempotencia.

Verificar la integración

Envíe accesorios conocidos de éxito y fracaso, luego consulte:

SELECT timestamp_utc, event_id, job_name, status, duration_ms, error_type
FROM job_completed
ORDER BY timestamp_utc DESC
LIMIT 20;

Verifique los nombres de las tablas, los tipos de campos, las unidades, el comportamiento nulo, los ID de eventos duplicados y los límites de los datos confidenciales. Realice un tiempo de espera de conexión y un cierre ordenado antes de confiar en el evento para recibir una alerta.

Solución de problemas

• Error de clave faltante: inicialice el cliente desde un valor de entorno del lado del servidor que no esté vacío.
• Bloqueos en tiempo de ejecución: mueva las llamadas de bloqueo de los subprocesos ejecutores asíncronos o utilice un cliente asíncrono HTTP propiedad de la aplicación.
• La respuesta de error se decodifica como JSON: inspeccione el estado y el mensaje devuelto; la caja no llama error_for_status.
• Filas duplicadas: conserve event_id en todos los intentos de red y supervise identificaciones duplicadas.
• Exportación grande: utilice el flujo de inicio, estado y descarga de consultas asíncronas HTTP.

Continúe con Registro API, solución de problemas de ingestión y lista de verificación de instrumentación de producción.