SDK de Go

Utilice telemetry-go para eventos sincrónicos directos y llamadas de consulta desde un servicio Go. El cliente publicado crea una solicitud HTTP para cada llamada a método. No expone el contexto, un http.Client personalizado, un tiempo de espera de SDK, reintentos automáticos, procesamiento por lotes ni una cola de vaciado.

Instalar e inicializar

go get github.com/telemetry-sh/telemetry-go

import (
    "os"

    telemetry "github.com/telemetry-sh/telemetry-go"
)

telemetryClient := telemetry.NewTelemetry()
telemetryClient.Init(os.Getenv("TELEMETRY_API_KEY"))

Inicialice un cliente durante el inicio de la aplicación. Utilice una clave con ámbito de escritura para la ingesta y una clave con ámbito de lectura para la automatización de solo consultas.

Enviar un evento estructurado

event := map[string]interface{}{
    "event_id":      eventID,
    "route_template": "/api/projects/:id",
    "method":         "POST",
    "status_code":    201,
    "status":         "success",
    "latency_ms":     float64(time.Since(startedAt).Microseconds()) / 1000,
    "request_id":     requestID,
    "release":        os.Getenv("APP_RELEASE"),
}

response, err := telemetryClient.Log("api_request_completed", event)
if err != nil {
    log.Printf("telemetry delivery failed event_id=%s error_type=transport_error", eventID)
}
_ = response

No envíe rutas de solicitud sin procesar que contengan identificadores, encabezados, cookies, cuerpos de solicitud, credenciales o contenido privado del cliente. Utilice un patrón de ruta normalizado y una categoría de error controlada.

El Go SDK acepta un map[string]interface{} por llamada Log. Utilice el registro HTTP API directamente si un trabajador propiedad de la aplicación necesita una ingesta masiva.

Ejecutar una consulta

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
`

result, err := telemetryClient.Query(query)
if err != nil {
    return fmt.Errorf("query telemetry: %w", err)
}

rows, _ := result["data"].([]interface{})
fmt.Printf("rows=%d\n", len(rows))

La respuesta utiliza mapas y sectores genéricos. Verifique los tipos, los campos faltantes, el estado de API y los resultados vacíos antes de usar un valor en la automatización. Utilice el Consulta asincrónica API para exportaciones grandes de JSON o Parquet.

Límite de transporte de producción

El SDK actual construye http.Client{} sin tiempo de espera. Por lo tanto, una solicitud de red detenida puede superar el presupuesto de latencia de un controlador o trabajador HTTP. Cuando se requiere un tiempo de espera limitado, cancelación de contexto, configuración del grupo de conexiones, carga útil masiva o manejo de estado explícito, incluya el contrato Telemetry HTTP en el http.Client existente del servicio.

Mantenga el mismo esquema de eventos y reglas de autorización:

client := &http.Client{Timeout: 2 * time.Second}

Utilice ese cliente para POST https://api.telemetry.sh/log con un cuerpo JSON que contenga table y data. Verifique el estado del HTTP antes de decodificar la respuesta.

Política de reintento y ruta crítica

Reintente solo fallas de conexión transitorias, 429, 502, 503 y 504. Aplique un retroceso exponencial con fluctuación, limite el tiempo transcurrido y reutilice el mismo event_id. No vuelva a intentar un esquema sin cambios ni solicite un error.

Para análisis de aplicaciones normales, no reemplace una respuesta completa del cliente porque falló la telemetría. Para eventos de facturación o auditoría aprobados que requieren durabilidad, persista un registro de la bandeja de salida en el sistema propietario de la transacción comercial y entréguelo de un trabajador.

Ver entrega de eventos e idempotencia y procesamiento por lotes y contrapresión.

Verificar la integración

Envíe eventos sintéticos de éxito, error, reintento y tiempo de espera, luego 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 campo, las unidades y la ausencia de contenido confidencial. Cierre del proceso de prueba y solicitud Telemetry detenida antes de conectar la instrumentación a un controlador de alto tráfico.

Solución de problemas

• Error de inicialización: confirme que la clave del lado del servidor no esté vacía antes de la primera llamada al método.
• La solicitud se bloquea: use el HTTP API a través de un cliente con un tiempo de espera y un contexto de solicitud.
• La respuesta de no éxito aparece como datos: inspeccione el campo de estado devuelto; el SDK actual decodifica el cuerpo JSON sin exigir el éxito del HTTP.
• Rechazo de esquema: mantenga estable el tipo de campo y elimine formas nulas o no compatibles.
• Filas duplicadas después del reintento: conserve event_id y audite con receta de evento duplicado.

Continúe con Ir al registro estructurado del servidor HTTP, Registro API y límites de velocidad y errores API.