SDK de JavaScript y TypeScript

Utilice el paquete telemetry-sh en JavaScript o TypeScript del lado del servidor. El cliente actual expone llamadas inmediatas a log y query a través de compilaciones ESM y CommonJS. No mantiene una cola de eventos en segundo plano ni expone un método de descarga.

No inicialice el paquete en el código del navegador: una clave Telemetry API otorga acceso a un equipo y no debe enviarse en un paquete de cliente.

Instalar e inicializar

npm install telemetry-sh

Módulos ES:

import telemetry from "telemetry-sh";

telemetry.init(process.env.TELEMETRY_API_KEY);

JS común:

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

Llame a init una vez durante el inicio del servidor o del trabajador. Utilice una clave con ámbito de escritura para código de solo ingesta y una clave con alcance de lectura para informes o automatización de solo consulta.

Enviar un evento estructurado

Espere la promesa devuelta cuando la aplicación necesite observar el éxito o el fracaso de la entrega:

const eventId = crypto.randomUUID();

try {
  await telemetry.log("api_request_completed", {
    event_id: eventId,
    route_template: "/api/projects/:id",
    method: "POST",
    status_code: 201,
    status: "success",
    latency_ms: 184,
    environment: process.env.APP_ENV,
    release: process.env.APP_RELEASE,
  });
} catch (error) {
  console.error("Telemetry delivery failed", {
    event_id: eventId,
    error_type: "telemetry_delivery_failed",
  });
}

Mantenga las URL sin procesar, los cuerpos de solicitud, las cookies, los encabezados de autorización, los secretos, las indicaciones y el contenido privado del cliente fuera de la carga útil. Utilice plantillas de ruta estables, identificadores internos y categorías de error controladas.

enviar un lote

log acepta una variedad de objetos compatibles. Un lote reduce la sobrecarga de solicitudes pero aumenta la cantidad de eventos afectados por una solicitud fallida.

await telemetry.log("job_completed", [
  {
    event_id: "evt_job_101",
    job_name: "invoice_sync",
    status: "success",
    duration_ms: 912,
  },
  {
    event_id: "evt_job_102",
    job_name: "invoice_sync",
    status: "failed",
    duration_ms: 2401,
    error_type: "provider_timeout",
  },
]);

El cliente JavaScript envía la matriz suministrada inmediatamente. No recopila llamadas en un lote interno. Si la aplicación introduce su propio búfer, limite su tamaño, antigüedad, presupuesto de reintento y comportamiento de apagado como se describe en procesamiento por lotes y contrapresión.

Ejecutar una consulta escrita

type ReliabilityRow = {
  requests: number;
  route_template: string;
};

const result = await telemetry.query<ReliabilityRow>(`
  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
`);

for (const row of result.data) {
  console.log(row.route_template, row.requests);
}

El tipo genérico describe filas de resultados para TypeScript; no valida los resultados de SQL en tiempo de ejecución. Verifique los resultados vacíos y los nulos inesperados antes de utilizar una consulta en automatización.

El método query de SDK llama al punto final de consulta interactiva. Utilice el flujo HTTP documentado para exportaciones asincrónicas JSON o Parquet en lugar de asumir que una opción SDK crea y sondea un trabajo asíncrono.

Comportamiento de entrega y reintentos

El paquete actual realiza una solicitud fetch por cada llamada log o query. No agrega un tiempo de espera SDK, un reintento automático, una cola persistente ni un ciclo de vida de vaciado.

Si vuelve a intentar la ingestión:

1. Vuelva a intentar solo errores de transporte transitorios, 429, 502, 503 y 504.
2. Reutilice el event_id del evento lógico.
3. Aplicar retroceso exponencial con fluctuación.
4. Intentos de límite y tiempo transcurrido.
5. No convierta una acción completada por el cliente en una falla a menos que la telemetría sea explícitamente parte del contrato de durabilidad de ese flujo de trabajo.

Utilice una bandeja de salida duradera propiedad de la aplicación para facturación o eventos de auditoría aprobados que no se pueden descartar. Ver entrega de eventos e idempotencia.

Verificar la integración

Después de enviar eventos sintéticos de éxito y fracaso, ejecute:

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

Confirme el nombre de la tabla, los tipos de campos, el comportamiento nulo, las marcas de tiempo UTC y la ausencia de campos confidenciales. Luego pruebe las ramas de reintento, tiempo de espera y cierre antes de crear un panel o una alerta.

Solución de problemas

• API key is not initialized: llame a telemetry.init antes del primer método SDK.
• 401: reemplace la clave faltante, inválida o revocada.
• 403: utilice una clave con el alcance requerido.
• 400: inspecciona el nombre de la tabla, la forma de JSON y la compatibilidad del tipo de campo; no lo vuelva a intentar sin cambios.
• 429 o 5xx: utilice una política de reintento limitada si el evento se puede entregar de forma segura más de una vez.
• El proceso sale antes de la entrega: rastree y espere llamadas inmediatas, o persista los eventos requeridos antes del cierre; no hay cola de vaciado SDK.

Continúe con Registro API, límites de velocidad y errores API y Integración de Node.js y Express.