OpenTelemetry

O BoxOffice é escrito em Java (gateway, order, inventory, payment, catalog) e Python (o assistant de IA), roda Nginx na borda, Kafka no meio e PostgreSQL embaixo. Dez anos atrás, rastrear um checkout por tudo isso significava um agente de fornecedor por linguagem, um header proprietário por fornecedor e uma reinstrumentação completa no dia em que a empresa trocasse de fornecedor. Pior: um trace se quebrava no primeiro componente que falasse outro dialeto. O OpenTelemetry (OTel) resolveu isso padronizando as partes chatas — a API, o protocolo de transmissão, o header de contexto e os nomes das coisas — para que toda biblioteca e todo backend falem a mesma língua¹. (As ideias em si — trace IDs, spans, ligações pai-filho, amostragem — vêm do artigo do Dapper, do Google⁴.)

O que o OpenTelemetry é (e o que não é)

O OpenTelemetry é um projeto da CNCF que define como a telemetria é produzida e transportada. Ele não é um backend: não armazena nem exibe nada. Você continua escolhendo para onde os dados vão — Prometheus, Tempo, Jaeger, Loki, um serviço de nuvem ou um fornecedor — e pode mudar essa escolha sem tocar no código da aplicação.

Os sinais amadureceram em ritmos diferentes: traces e métricas são estáveis, logs ficaram estáveis depois (o OTel principalmente faz a ponte com bibliotecas de logging existentes, adicionando o contexto de trace), e os profiles foram adicionados como quarto sinal e ainda estão amadurecendo.

flowchart LR
    subgraph services ["Serviços do BoxOffice"]
        J["Serviços Java<br/>agente Java OTel"]
        PY["assistant (Python)<br/>SDK OTel"]
        NG["Nginx<br/>módulo OTel"]
    end
    subgraph col ["OTel Collector"]
        R["receivers<br/>otlp"] --> PR["processors<br/>memory_limiter, atributos k8s,<br/>remoção, tail sampling, batch"] --> E["exporters"]
    end
    J -- OTLP --> R
    PY -- OTLP --> R
    NG -- OTLP --> R
    E --> TEMPO[("Tempo / Jaeger<br/>traces")]
    E --> PROM[("Prometheus / Mimir<br/>métricas")]
    E --> LOKI[("Loki<br/>logs")]

Propagação de contexto

Um trace só existe se cada salto souber a qual trace pertence. A propagação de contexto é o mecanismo: quem chama injeta o contexto de trace atual na requisição de saída, e quem é chamado o extrai e cria o próprio span como filho.

O header traceparent

O OpenTelemetry usa por padrão o padrão W3C Trace Context². Um único header carrega o contexto:

traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
             │  │                                │                └─ flags: 01 = sampled
             │  │                                └─ parent-id: the caller's current span (64 bits)
             │  └─ trace-id: same for the whole request (128 bits)
             └─ version

Em cada chamada de saída, um serviço mantém o trace-id e as flags e substitui o parent-id pelo ID do seu próprio span atual. Nenhum serviço precisa entender o trace inteiro; a árvore é reconstruída pelo backend a partir das ligações com o pai. Um segundo header, tracestate, carrega dados específicos de fornecedor, e o baggage (baggage: tenant=festival-x,channel=mobile) carrega pares chave-valor de negócio que todo serviço adiante pode ler — útil, mas cada byte viaja em cada requisição, então mantenha-o pequeno e nunca coloque segredos nele.

Acompanhando um checkout

Execute o diagrama e observe o parent-id mudar a cada salto enquanto o trace-id permanece o mesmo — inclusive através do Kafka, onde o contexto viaja num header da mensagem:

sequenceDiagram
    autonumber
    participant GW as gateway
    participant O as order
    participant I as inventory
    participant P as payment
    participant X as provedor de pagamentos
    participant K as Kafka
    participant N as notification
    GW->>O: POST /orders<br/>traceparent: 00-4bf9…-a1a1…-01
    O->>I: PUT /holds/h7/confirm<br/>traceparent: 00-4bf9…-b2b2…-01
    I-->>O: 200 OK (90 ms)
    O->>P: POST /charges<br/>traceparent: 00-4bf9…-c3c3…-01
    P->>X: POST /v1/charges (span CLIENT registrado pelo payment)
    X-->>P: 200 OK (1,0 s)
    P-->>O: 201 Created
    O->>K: produz OrderConfirmed<br/>header traceparent: 00-4bf9…-d4d4…-01
    O-->>GW: 201 Created
    K->>N: consome OrderConfirmed (span CONSUMER, pai d4d4…)
    N->>N: envia e-mail e push

Três detalhes importam na prática:

• O provedor externo é uma caixa-preta. Ele não vai enviar os spans dele para você. O span CLIENT registrado pelo payment em torno da chamada é tudo o que você vai ver dele — e é por isso que a duração e o status desse span merecem um alerta próprio. Muitos times também removem traceparent e baggage na saída, para que IDs internos não vazem para terceiros.
• Saltos assíncronos propagam pelos headers das mensagens. Um consumidor que trata uma mensagem continua o trace do produtor (pai-filho). Um consumidor que processa um lote de 500 mensagens não pode ter 500 pais; ele inicia o próprio trace e adiciona span links para o span de cada produtor.
• O trace termina onde a propagação quebra. Um componente que descarta o header divide todos os traces em dois.

@Transactional(propagation = Propagation.MANDATORY)
public void append(UUID eventId, String aggregateType, UUID aggregateId, String eventType, Object payload) {
    String json = mapper.writeValueAsString(payload); // Jackson 3: exceptions are unchecked
    // capture the trace context of the current request (null without the agent)
    Map<String, String> carrier = new HashMap<>();
    W3CTraceContextPropagator.getInstance().inject(Context.current(), carrier, (c, k, v) -> c.put(k, v));

    jdbc.sql("""
            INSERT INTO outbox (id, aggregate_type, aggregate_id, event_type, payload, traceparent)
            VALUES (?, ?, ?, ?, ?::jsonb, ?)
            """)
            .params(eventId, aggregateType, aggregateId, eventType, json, carrier.get("traceparent"))
            .update();
}

for (Pending p : batch) {
    ProducerRecord<String, String> record =
            new ProducerRecord<>(topic, p.aggregateId().toString(), p.payload());
    record.headers().add("eventId", p.id().toString().getBytes(StandardCharsets.UTF_8));
    record.headers().add("eventType", p.eventType().getBytes(StandardCharsets.UTF_8));
    // continue the trace of the request that created the event
    Context origin = W3CTraceContextPropagator.getInstance().extract(Context.root(), p, ROW);
    try (Scope ignored = origin.makeCurrent()) {
        acks.add(kafka.send(record)); // the agent's producer span is a child of the request
    }
}

Instrumentando o BoxOffice

Sem código: o agente Java

O agente Java do OpenTelemetry se anexa à JVM e instrumenta centenas de bibliotecas — Spring MVC/WebFlux, JDBC, HikariCP, clientes Kafka, clientes HTTP, Logback — por injeção de bytecode, sem mudanças no código. Ele também coloca trace_id e span_id no contexto de logging (MDC), então os logs estruturados os carregam automaticamente.

# Dockerfile (excerpt) — pin a version; check the latest release before upgrading
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v2.32.0/opentelemetry-javaagent.jar /otel/opentelemetry-javaagent.jar
ENTRYPOINT ["java", "-javaagent:/otel/opentelemetry-javaagent.jar", "-jar", "/app/app.jar"]

# docker-compose.yaml (excerpt) — the order service
environment:
  OTEL_SERVICE_NAME: order
  OTEL_RESOURCE_ATTRIBUTES: service.namespace=boxoffice,service.version=1.4.2,deployment.environment.name=dev
  OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318   # agent 2.x default protocol: http/protobuf
  OTEL_TRACES_SAMPLER: parentbased_always_on                 # keep all; the Collector decides (tail sampling)
  OTEL_METRIC_EXPORT_INTERVAL: "15000"

service.name é o atributo mais importante do OpenTelemetry: sem ele, todo serviço aparece como unknown_service:java e nenhum dashboard consegue distingui-los. service.version e deployment.environment.name permitem comparar um canary com a versão estável, ou staging com produção.

# lab 8: OpenTelemetry settings shared by every Java service (merged into each "environment")
x-otel: &otel
  JAVA_TOOL_OPTIONS: -javaagent:/otel/opentelemetry-javaagent.jar
  OTEL_JAVAAGENT_ENABLED: ${OTEL_ON:-true}          # false = same image, agent off
  OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-lgtm:4318
  OTEL_METRIC_EXPORT_INTERVAL: "10000"              # 10 s instead of 60 s
  OTEL_RESOURCE_ATTRIBUTES: service.namespace=boxoffice,deployment.environment.name=local
  OTEL_TRACES_SAMPLER: ${OTEL_TRACES_SAMPLER:-parentbased_always_on}
  OTEL_TRACES_SAMPLER_ARG: ${OTEL_TRACES_SAMPLER_ARG:-1.0}
  LOGGING_PATTERN_CORRELATION: "[%X{trace_id:-},%X{span_id:-}] "   # trace id in console logs
x-catalog: &catalog
  build: ./services/catalog
  image: boxoffice-catalog
  volumes:
    - ./infra/otel:/otel:ro          # lab 8: the Java agent
  environment:
    <<: *otel
    OTEL_SERVICE_NAME: catalog       # three replicas, ONE service

Sem código: o assistant em Python

uv add opentelemetry-distro opentelemetry-exporter-otlp
uv run opentelemetry-bootstrap -a requirements > otel-instrumentations.txt   # instrumentations for the libraries found (FastAPI, httpx, psycopg…)
uv add -r otel-instrumentations.txt
OTEL_SERVICE_NAME=assistant \
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 \
uv run opentelemetry-instrument uvicorn app.main:app --host 0.0.0.0 --port 8000

Spans manuais onde o agente não enxerga

A instrumentação automática enxerga I/O. Ela não enxerga etapas de negócio nem espera dentro do seu código — o pool de conexões do adaptador de pagamentos no waterfall de Sinais. Alguns spans manuais nos lugares certos valem mais que centenas de spans automáticos:

private static final Tracer tracer = GlobalOpenTelemetry.getTracer("boxoffice.payment");

ProviderConnection acquire() throws TimeoutException {
    Span span = tracer.spanBuilder("pool.acquire").startSpan();
    try (Scope ignored = span.makeCurrent()) {
        long start = System.nanoTime();
        ProviderConnection c = pool.borrow(Duration.ofMillis(500));   // bounded wait, never forever
        span.setAttribute("pool.wait_ms", (System.nanoTime() - start) / 1_000_000);
        return c;
    } catch (TimeoutException e) {
        span.recordException(e);
        span.setStatus(StatusCode.ERROR, "pool exhausted");
        throw e;
    } finally {
        span.end();
    }
}

Com o agente anexado, a alternativa mais simples é uma anotação no método: @WithSpan("seatmap.render"), com @SpanAttribute nos parâmetros que você quer registrar.

O Collector

Os serviços poderiam exportar direto para cada backend, mas aí cada serviço precisaria conhecer cada backend, suas credenciais e sua política de retry. O Collector os desacopla: os serviços enviam OTLP para um só lugar, e os pipelines do Collector decidem o que acontece em seguida. Um pipeline tem três estágios por sinal: receivers (como os dados entram), processors (o que é feito com eles, em ordem), exporters (para onde vão).

# otel-collector.yaml — gateway Collector for BoxOffice (sketch)
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
      http: { endpoint: 0.0.0.0:4318 }

processors:
  memory_limiter:                 # first: refuse data instead of being OOM-killed
    check_interval: 1s
    limit_percentage: 80
    spike_limit_percentage: 20
  k8sattributes: {}               # add k8s.pod.name, k8s.namespace.name, k8s.deployment.name
  attributes/redact:
    actions:
      - key: payment.card_number
        action: delete
      - key: enduser.email
        action: hash
  tail_sampling:
    decision_wait: 10s            # wait for the trace's spans before deciding
    policies:
      - name: keep-errors
        type: status_code
        status_code: { status_codes: [ERROR] }
      - name: keep-slow
        type: latency
        latency: { threshold_ms: 2000 }
      - name: some-of-the-rest
        type: probabilistic
        probabilistic: { sampling_percentage: 5 }
  batch: {}                       # last: send in batches

exporters:
  otlp/tempo:
    endpoint: tempo:4317
    tls: { insecure: true }
  otlphttp/prometheus:
    endpoint: http://prometheus:9090/api/v1/otlp
  otlphttp/loki:
    endpoint: http://loki:3100/otlp

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, k8sattributes, attributes/redact, tail_sampling, batch]
      exporters: [otlp/tempo]
    metrics:
      receivers: [otlp]
      processors: [memory_limiter, k8sattributes, batch]
      exporters: [otlphttp/prometheus]
    logs:
      receivers: [otlp]
      processors: [memory_limiter, k8sattributes, attributes/redact, batch]
      exporters: [otlphttp/loki]

A ordem dos processors importa: memory_limiter primeiro, para que um Collector sobrecarregado descarte dados em vez de cair; batch por último, para agrupar o que sobreviveu.

Padrões de implantação

Amostragem (sampling)

Guardar todos os spans de todas as requisições raramente cabe no orçamento (veja quanto custa a telemetria). A amostragem guarda um subconjunto dos traces — traces completos, não spans aleatórios, senão as árvores se quebram.

Head e tail sampling são aplicados em sequência: um trace descartado na cabeça nunca pode ser resgatado na cauda. A comparação abaixo usa números ilustrativos para um dia movimentado do BoxOffice — 2.000 requisições/s, 8 spans por requisição de 500 bytes, 1% das requisições falhando e 2% mais lentas que o limiar de 2 s:

O tail sampling armazena menos que o head sampling de 10% e ainda guarda todos os traces de erro — ao preço de enviar 100% dos spans pela rede até o Collector e mantê-los em buffer durante a janela de decisão. Uma receita comum em produção: head sampling de 100% (ou uma razão alta) nos serviços, tail sampling num Collector gateway, e métricas calculadas a partir de todas as requisições antes da amostragem, para que dashboards e SLOs sejam exatos mesmo que a maioria dos traces seja descartada.

Backends e uma stack local

O OpenTelemetry deixa o backend por sua conta. Os mesmos dados OTLP podem ir para qualquer um deles:

Para desenvolvimento — e no Hands-on 8 — um único container junta um Collector com toda a stack LGTM:

# docker-compose.yaml (excerpt)
services:
  otel-lgtm:
    image: grafana/otel-lgtm
    ports:
      - "3000:3000"   # Grafana
      - "4317:4317"   # OTLP gRPC
      - "4318:4318"   # OTLP HTTP

Trade-offs

Como se conecta

flowchart LR
    KH["Kafka message headers,<br/>span links → Messaging"] --> CTX["context propagation:<br/>traceparent, baggage"]
    CTX --> SVC["services: Java agent,<br/>Python SDK, Nginx"]
    SVC -->|"OTLP 4317 / 4318"| COL["Collector:<br/>receivers → processors → exporters"]
    COL --> RD["redaction:<br/>no cards, no e-mails"]
    COL --> TS["tail sampling:<br/>errors + slow + 5%"]
    TS --> TR["traces backend<br/>Tempo / Jaeger"]
    COL --> MET["metrics from all traffic<br/>→ SLOs, Alerting"]
    COL --> LG["logs backend<br/>Loki"]
    MET -->|"exemplars"| TR
    COL --> OPS["memory_limiter, gateway replicas<br/>→ Cloud-native"]

Componentes da paleta: tracing · metrics · logs · app (serviços instrumentados) · apigw (precisa repassar o traceparent) · kafka (contexto nos headers das mensagens) · payment (uma caixa-preta: só o span CLIENT). Cenários: observability-stack, event-fanout (traces que atravessam o Kafka). Continua em: Sinais, Alertas, Mensageria — Kafka, Cloud-native — Kubernetes (Collector como DaemonSet ou Deployment), Hands-on 8 — instrumentar tudo.

Pontos-chave