Integración Ruby HTTP

Telemetry HTTP API funciona con la biblioteca estándar de Ruby. Esto mantiene pequeña la superficie de dependencia y deja la política de tiempo de espera, reintento y durabilidad bajo el control de la aplicación.

Configurar y enviar un evento

require "json"
require "net/http"
require "uri"

api_key = ENV.fetch("TELEMETRY_API_KEY")
uri = URI("https://api.telemetry.sh/log")

request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
  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
  }
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true,
  open_timeout: 2,
  read_timeout: 10
) { |http| http.request(request) }

unless response.is_a?(Net::HTTPSuccess)
  raise "Telemetry log failed with HTTP #{response.code}"
end

Telemetry agrega timestamp_utc. Mantenga la clave del lado del servidor y no envíe credenciales, cookies, encabezados, parámetros de solicitud, mensajes de excepción sin procesar ni contenido privado del cliente.

enviar un lote

Configure data en una matriz:

request.body = {
  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"
    }
  ]
}.to_json

Mantenga un lote delimitado y compatible con el esquema. Una cola propiedad de la aplicación también necesita una profundidad máxima, una antigüedad máxima, una regla de desbordamiento, un presupuesto de reintento y una fecha límite de cierre.

Ejecute SQL

Utilice una clave de alcance de lectura:

uri = URI("https://api.telemetry.sh/query")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = api_key
request["Content-Type"] = "application/json"
request.body = {
  query: <<~SQL
    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;
  SQL
}.to_json

response = Net::HTTP.start(
  uri.hostname,
  uri.port,
  use_ssl: true,
  open_timeout: 2,
  read_timeout: 30
) { |http| http.request(request) }

raise "Telemetry query failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)

result = JSON.parse(response.body)
Array(result["data"]).each do |row|
  # Validate expected keys and nulls before using the row.
end

Utilice el Consulta asincrónica API para exportaciones grandes de JSON o Parquet.

Política de reintentos y fallos

Net::OpenTimeout significa que no se pudo establecer una conexión. Net::ReadTimeout es ambiguo porque es posible que el servidor haya aceptado la solicitud antes de que se perdiera la respuesta.

Reintente solo fallas de red transitorias, 429, 502, 503 y 504. Reutilice el event_id del evento lógico, aplique un retroceso exponencial con fluctuación y limite el tiempo total transcurrido. No vuelva a intentar una solicitud no válida y sin cambios.

Para análisis normales, una interrupción de la telemetría no debe reemplazar una respuesta completa del cliente. Continúe la facturación o los eventos de auditoría aprobados en una bandeja de salida duradera propiedad de la aplicación cuando la pérdida no sea aceptable.

Verificar y solucionar problemas

Envíe eventos sintéticos de éxito y fracaso, consulte las filas más recientes e inspeccione GET /tables/<table>/schema.

• KeyError: configura la clave API en el entorno del servidor o trabajador.
• 401 o 403: sustituir la llave o corregir su alcance.
• 400: inspecciona el nombre de la tabla, la forma de JSON y la compatibilidad del tipo de campo.
• Tiempo de espera: aplique la política de reintento o reserva documentada del flujo de trabajo sin imprimir la carga útil.
• Cierre del proceso: las llamadas directas HTTP no tienen cola en segundo plano para vaciar; rastrear las llamadas requeridas o persistir eventos primero.

Consulte Integración de rieles, Registro API, guía de entrega de eventos y solución de problemas de ingestión.