Traces

Distributed tracing é o terceiro backend L1 depois de Prom e Loki. Como eles, segue o ADR-014: edges fazem push direto, manager só consulta.

O 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 roda como um plugin sob o edge agent (mesmo modelo de supervisão de promtail — veja Logs). O collector aceita tanto gRPC (:4317) quanto HTTP (:4318) no host, faz batch, e encaminha para o Tempo do cloud via HTTPS.

Apps não precisam saber do Ongrid

Configure o exporter OTel da sua aplicação para apontar a http://localhost:4318 (ou o equivalente gRPC). O otelcol local trata auth + batch + a viagem ao cloud. Remover o Ongrid significa remover uma única variável de env — seu código fica intacto.

O gerador spanmetrics

O deployment Tempo no compose tem metrics_generator habilitado. Cada batch de spans produz três métricas derivadas emitidas de volta no mesmo Prom:

Série	Fonte
traces_spanmetrics_calls_total	um counter por (service, operation, status_code)
traces_spanmetrics_latency_bucket	histograma de duração de span
traces_spanmetrics_size_bucket	opcional, off por padrão

Esse é o truque load-bearing que faz alertas de trace parecerem alertas de metric: o evaluator de alerta consulta o Prom, o dado vive no Tempo.

Categorias 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 para:

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 é opcional — descarte para latência a nível de serviço. Veja compileTraceLatencyRule.

Quantis suportados: p50 / p95 (padrão) / p99. A forma string existe para o picker do form da UI ficar curto; o compiler mapeia para o float que histogram_quantile quer.

trace_error_rate

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

Compila para:

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

O literal STATUS_CODE_ERROR é o que o gerador spanmetrics emite; convenções alternativas de status de span precisam do próprio kind.

Tools

query_traceql

Passthrough direto ao endpoint TraceQL do Tempo (query_traceql_basetool.go). Usado pela persona investigator quando o operador pede IDs de trace específicos — ex.: "encontre um trace lento para payments-api nos últimos 30 minutos".

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

O client subjacente é internal/pkg/tracequery; nome de pacote desacoplado do backend de propósito — clients Jaeger / Zipkin podem entrar depois sem renomear a superfície.

correlate_incident

A tool composta com que a persona investigator começa. Puxa sinais de Prom + Loki + Tempo em torno da janela de disparo do incidente em uma única chamada de fan-out. Reduz 4-5 chamadas de tool sequenciais a uma — importante quando o budget por investigação é de 10 chamadas de tool.

Veja correlate_incident_basetool.go.

Veja também

• Alertas — os kinds de rule.
• Monitoramento — o backend Prom que as alertas de trace consultam.
• Topologia — arestas service-to-service que o metrics_generator do Tempo infere automaticamente.
• Data plane de telemetria — ADR-014 por inteiro.