Ejemplos de cURL y HTTP API

Utilice cURL para verificar una clave API, reproducir una solicitud SDK, automatizar un script del lado del servidor o probar el manejo de fallas antes de agregar instrumentación a una aplicación.

Configurar la clave

Exporte la clave en un shell que no registre valores secretos:

export TELEMETRY_API_KEY="YOUR_API_KEY"

Utilice una clave con ámbito de escritura para la ingesta y una clave con ámbito de lectura independiente para consultas o informes. Deshabilite el rastreo de shell alrededor de los comandos que expanden la clave.

Enviar un evento

curl --fail-with-body \
  --connect-timeout 2 \
  --max-time 10 \
  --request POST \
  "https://api.telemetry.sh/log" \
  --header "Authorization: ${TELEMETRY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "table": "api_request_completed",
  "data": {
    "event_id": "evt_request_101",
    "route_template": "/api/projects/:id",
    "method": "GET",
    "status_code": 200,
    "status": "success",
    "latency_ms": 184
  }
}
JSON

Telemetry agrega timestamp_utc. No envíe claves API, encabezados de autorización, cookies, cuerpos de solicitud sin procesar, mensajes ni contenido privado del cliente como campos de eventos.

Enviar un lote compatible

El campo data puede ser una matriz:

curl --fail-with-body \
  --connect-timeout 2 \
  --max-time 10 \
  --request POST \
  "https://api.telemetry.sh/log" \
  --header "Authorization: ${TELEMETRY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "table": "job_completed",
  "data": [
    {
      "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"
    }
  ]
}
JSON

Mantenga todos los objetos compatibles con el mismo esquema de tabla. Un lote reduce la sobrecarga de solicitudes pero aumenta la cantidad de eventos afectados por una solicitud fallida.

Ejecute SQL

curl --fail-with-body \
  --connect-timeout 2 \
  --max-time 30 \
  --request POST \
  "https://api.telemetry.sh/query" \
  --header "Authorization: ${TELEMETRY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "SELECT route_template, COUNT(*) AS requests, ROUND(AVG(latency_ms), 0) AS avg_latency_ms FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '24 hours' GROUP BY route_template ORDER BY requests DESC;"
}
JSON

Verifique los campos status, data y key_order en lugar de asumir un resultado que no esté vacío.

Exportar un resultado más grande

Inicie una exportación asincrónica de Parquet:

curl --fail-with-body \
  --connect-timeout 2 \
  --max-time 30 \
  --request POST \
  "https://api.telemetry.sh/query/async" \
  --header "Authorization: ${TELEMETRY_API_KEY}" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "query": "SELECT * FROM api_request_completed WHERE timestamp_utc >= now() - INTERVAL '30 days' ORDER BY timestamp_utc DESC;",
  "format": "parquet"
}
JSON

Sondee el status_url devuelto con el mismo encabezado de autorización. Cuando query_status sea completed, descargue download_url. Deje de realizar encuestas en failed y aplique una fecha límite general.

Inspeccionar y verificar la tabla.

curl --fail-with-body \
  --connect-timeout 2 \
  --max-time 10 \
  "https://api.telemetry.sh/tables/api_request_completed/schema" \
  --header "Authorization: ${TELEMETRY_API_KEY}"

Envíe casos sintéticos de éxito, error, reintento y tiempo de espera. Confirme los tipos de campos, las unidades, las marcas de tiempo UTC y la ausencia de campos confidenciales antes de crear un panel o una alerta.

Política de reintento y código de salida

--fail-with-body sale de un valor distinto de cero para fallas de HTTP y al mismo tiempo conserva el cuerpo de respuesta para un diagnóstico seguro.

• Salga de 6: Error en la resolución de DNS.
• Salga de 7: la conexión falló.
• Salir de 28: tiempo de espera; el servidor puede haber aceptado o no la solicitud.
• HTTP 400: arreglar la solicitud; no lo vuelva a intentar sin cambios.
• HTTP 401 o 403: reemplazar la credencial o corregir su alcance.
• HTTP 429, 502, 503 o 504: reintento con jitter y retroceso exponencial limitado.

Reutilice el mismo event_id para un evento lógico. No utilice --retry-all-errors sin tener en cuenta la entrega duplicada.

Consulte Registro API, Consulta API, Tablas API y guía de entrega de eventos.