Trazas

El tracing distribuido es el tercer backend de L1 después de Prom y Loki. Como ellos, sigue ADR-014: los edges empujan directo, el manager solo consulta.

El data plane

your apps (OTLP gRPC/HTTP)
    │
    ▼
edge:
  otelcol (subprocess plugin)
    └─ remote OTLP → tempo:4317
                          │
                          ├─ trace storage (S3-compatible blob)
                          │
                          └─ metrics_generator → traces_spanmetrics_*
                                                       │
                                                       ▼
                                                 prometheus:9090

otelcol corre como un plugin bajo el agente edge (mismo modelo de supervisión que promtail — ver Logs). El collector acepta tanto gRPC (:4317) como HTTP (:4318) en el host, batchea y reenvía al Tempo de la nube sobre HTTPS.

Las apps no necesitan saber sobre Ongrid

Configura el exporter de OTel de tu aplicación para apuntar a http://localhost:4318 (o el equivalente gRPC). El otelcol local maneja auth + batching + el viaje a la nube. Quitar Ongrid significa quitar una env var — tu código queda intocado.

El generador de spanmetrics

El despliegue de Tempo en el compose tiene metrics_generator habilitado. Cada batch de spans produce tres métricas derivadas emitidas de vuelta al mismo Prom:

Serie	Fuente
traces_spanmetrics_calls_total	un counter por (service, operation, status_code)
traces_spanmetrics_latency_bucket	histogram de duración de span
traces_spanmetrics_size_bucket	opcional, off por defecto

Este es el truco load-bearing que hace que las alertas de traza se sientan como alertas de métrica: el evaluator de alertas consulta Prom, la data vive en Tempo.

Kinds de alerta

trace_latency

{
  "kind": "trace_latency",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "operation": "POST /v1/charge",
    "quantile": "p95",
    "window": "5m",
    "threshold_ms": 800
  }
}

Compila a:

histogram_quantile(
  0.95,
  sum by (le) (rate(traces_spanmetrics_latency_bucket{
    service_name="payments-api", span_name="POST /v1/charge"
  }[5m]))
) * 1000 > 800

operation es opcional — quítalo para latencia service-wide. Ver compileTraceLatencyRule.

Quantiles soportados: p50 / p95 (default) / p99. La forma string existe para que el picker del formulario UI se mantenga terso; el compilador mapea al float que quiere histogram_quantile.

trace_error_rate

{
  "kind": "trace_error_rate",
  "scope_type": "global",
  "conditions_json": {
    "service": "payments-api",
    "window": "5m",
    "operator": ">",
    "threshold_pct": 1.0
  }
}

Compila a:

100 * (
  sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api", status_code="STATUS_CODE_ERROR"
  }[5m]))
  / sum by (service_name) (rate(traces_spanmetrics_calls_total{
    service_name="payments-api"
  }[5m]))
) > 1.0

El literal STATUS_CODE_ERROR es lo que emite el generador de spanmetrics; convenciones alternativas de status de span necesitan su propio kind.

Tools

query_traceql

Passthrough directo al endpoint TraceQL de Tempo (query_traceql_basetool.go). Usado por la persona investigator cuando el operador pide IDs de traza específicos — p. ej. "encuentra una traza lenta para payments-api en los últimos 30 minutos".

{ resource.service.name="payments-api" } | duration > 800ms

El cliente subyacente es internal/pkg/tracequery; nombre de paquete backend-decoupled a propósito — los clientes de Jaeger / Zipkin pueden caer sin renombrar la superficie.

correlate_incident

El tool compuesto con el que arranca la persona investigator. Jala señales de Prom + Loki + Tempo alrededor de la ventana de fire del incidente en una única llamada fan-out. Reduce 4-5 llamadas secuenciales de tool a una — importante cuando el presupuesto por investigación es de 10 llamadas de tool.

Ver correlate_incident_basetool.go.

Ver también

• Alertas — los rule kinds.
• Monitoring — el backend Prom que las alertas de traza consultan.
• Topología — edges service-to-service que el metrics_generator de Tempo infiere automáticamente.
• Data plane de telemetría — ADR-014 completo.