Distributed Tracing: OpenTelemetry

Distributed Tracing: OpenTelemetry

1) Porquê OTel e o que ele dá

• Visibilidade de passagem dos caminhos de consulta (gateway → serviços → BD/dinheiro/fila).
• Rápido RCA/depuração de degradações e lançamentos (canarinhos/blue-green).
• Ligação com SLO e reversíveis automáticos (soluções operacionais em dados).
• Vendor agnosticidade: exportação para qualquer backend, sem ligação com um APM.

Princípios de referência: standardize, sample smart, secure by default, correlate everything.

2) Fundamentos: contexto, spans, atributos

Trace - árvore/gráfico de chamadas; Span - Operação (RPC, SQL, chamada de fila).
Span Kind: `SERVER`, `CLIENT`, `PRODUCER`, `CONSUMER`, `INTERNAL`.
W3C Trace Context: títulos 'traceparent', 'tracestate'; o contexto é transferido entre os servidores.
Atributes - valor-chave (baixa cardealidade!), Events - marcas no tempo, Status - código/descrição do erro.
Links - comunicação de spans fora da hierarquia rigorosa (importante para async/fan-out/fan-in).

• HTTP: 'HTTP\METHOD' ('GET/withdraw' como atributo)
• DB: `DB SELECT` / `DB INSERT`
• Queue: `QUEUE publish topic=X` / `QUEUE consume topic=X`

3) Convenções semânticas (semconv)

• HTTP/GRPC: `http. method`, `http. route`, `http. status_code`, `url. full`.
• DB: `db. system=postgresql`, `db. statement '(só espremedor seguro!),' db. name`.
• Messaging: `messaging. system=kafka`, `messaging. operation=receive`, `messaging. destination`.
• Cloud/K8s/Host: `cloud. region`, `k8s. pod. name`, `container. id`.
• Resource atributes (obrigatório): 'service. name`, `service. version`, `deployment. environment`.

A estabilidade do esquema é indicada através de 'schemaUrl' em recursos SDK/Captor.

4) Sampling: head, tail, adaptável

Head-based (em SDK): resolve com antecedência, barato; bom para high-QPS, mas pode perder pistas «interessantes».
Tail-based (em Colector): resolve após a conclusão da pista; permite regras de status, latência, atributos.
Adaptativo/Dinâmico: eleva a proporção de sample com erros/altura p95.

Receita de nível prod: Head 1-5% global + Tail seleção «importante»: «status = ERRO», «latency> p95», «rotas de dinheiro», erros PSP/KYC.

5) Correlação: métricas, logs, trailers

Excempars: marcas com 'trace _ id' em histogramas de métricas (salto rápido para a pista).
Logi: Adicione 'trace _ id '/' span _ id' e passe dos logs para a pista.
SpanMetrics (processor): instala a partir de trechos de métricas RED ('requests, errors, duration') para alertas SLO.

6) Arquitetura de implantação

O Agente (DaemonSet) em cada nó é coletado a partir de aplicativos (OTLP) e de fiação.
Gateway (Cluster/Region) - Central Colector (muitas réplicas) com piplins de routing/sampling/enriquecimento.
OTLP: gRPC `4317`, HTTP `4318`; Liguem a TLS/mTLS.

Os benefícios de «agente + gateway» são isolamento, tampão, backpressure local, rede simplificada.

7) OpenTelemetry Colector - modelo básico (gateway)

yaml receivers:
otlp:
protocols:
grpc: { endpoint: 0. 0. 0. 0:4317 }
http: { endpoint: 0. 0. 0. 0:4318 }

processors:
memory_limiter: { check_interval: 5s, limit_percentage: 75 }
batch: { timeout: 2s, send_batch_size: 8192 }
attributes:
actions:
- key: deployment. environment action: upsert value: prod resource:
attributes:
- key: service. namespace action: upsert value: core tail_sampling:
decision_wait: 5s policies:
- name: errors type: status_code status_code: { status_codes: [ERROR] }
- name: slow_traces type: latency latency: { threshold_ms: 800 }
- name: important_routes type: string_attribute string_attribute:
key: http. route values: ["/withdraw", "/deposit"]
- name: baseline_prob type: probabilistic probabilistic: { sampling_percentage: 5 }

exporters:
otlp/apm:
endpoint: apm-backend:4317 tls: { insecure: true }
prometheus:
endpoint: 0. 0. 0. 0:9464

extensions:
health_check: {}
pprof: { endpoint: 0. 0. 0. 0:1777 }
zpages: { endpoint: 0. 0. 0. 0:55679 }

service:
extensions: [health_check, pprof, zpages]
pipelines:
traces:  { receivers: [otlp], processors: [memory_limiter,attributes,resource,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }
logs:   { receivers: [otlp], processors: [batch], exporters: [] }

8) SpanMetrics e RED para SLO

yaml processors:
spanmetrics:
metrics_exporter: prometheus histogram:
explicit:
buckets: [50ms,100ms,200ms,400ms,800ms,1600ms,3200ms]
service:
pipelines:
traces: { receivers: [otlp], processors: [spanmetrics,batch,tail_sampling], exporters: [otlp/apm] }
metrics: { receivers: [otlp], processors: [batch], exporters: [prometheus] }

Agora há 'traces _ spanmetrics' para SLO/alerts.

9) K8s: implantação do Captor (DaemonSet + Deployment)

yaml apiVersion: apps/v1 kind: DaemonSet metadata: { name: otel-agent, namespace: observability }
spec:
template:
spec:
containers:
- name: otelcol image: otel/opentelemetry-collector:latest args: ["--config=/conf/agent. yaml"]
ports:
- { containerPort: 4317, name: otlp-grpc }
- { containerPort: 4318, name: otlp-http }

Gateway - várias réplicas, Service ClusterIP/Ingress, HPA CPU/QPS.

10) Segurança e privacidade

TLS/mTLS между SDK → Agent → Gateway → Backend.
Autenticação (Basic/OAuth/Headers) na entrada do Gateway; limite as origens.
Redação PII: filtre/disfarce atributos ('user. email ',' card ') no processador Colector.
Limite: em SDK, limite o tamanho do evento/número de atributos (proteção contra a radicalidade).
RBAC em backand + projetos de neymspace/tenentes individuais.

yaml processors:
attributes/redact:
actions:
- key: user. email action: delete
- key: payment. card action: delete

11) Ferramentas: lançamentos rápidos

Node. js

js import { NodeSDK } from "@opentelemetry/sdk-node";
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-grpc";
import { Resource } from "@opentelemetry/resources";
import { SemanticResourceAttributes as R } from "@opentelemetry/semantic-conventions";

const sdk = new NodeSDK({
traceExporter: new OTLPTraceExporter({ url: "http://otel-agent. observability:4317" }),
resource: new Resource({
[R.SERVICE_NAME]: "payments-api",
[R.SERVICE_VERSION]: "1. 14. 2",
[R.DEPLOYMENT_ENVIRONMENT]: "prod"
}),
instrumentations: [getNodeAutoInstrumentations()],
});
sdk. start();

Java (Spring)

java
// Gradle: io. opentelemetry. instrumentation:opentelemetry-spring-boot-starter
// application. yml otel:
service:
name: orders-api exporter:
otlp:
endpoint: http://otel-agent. observability:4317 traces:
sampler: parentbased_traceidratio sampler-arg: 0. 05

Python (FastAPI)

python from opentelemetry import trace from opentelemetry. sdk. resources import Resource from opentelemetry. exporter. otlp. proto. grpc. trace_exporter import OTLPSpanExporter from opentelemetry. sdk. trace import TracerProvider from opentelemetry. sdk. trace. export import BatchSpanProcessor

provider = TracerProvider(resource=Resource. create({"service. name":"fraud-scoring","deployment. environment":"prod"}))
provider. add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://otel-agent. observability:4317", insecure=True)))
trace. set_tracer_provider(provider)

Go

go exp, _:= otlptracegrpc. New(ctx, otlptracegrpc. WithEndpoint("otel-agent. observability:4317"), otlptracegrpc. WithInsecure())
res:= resource. NewWithAttributes(semconv. SchemaURL, semconv. ServiceNameKey. String("gateway"), semconv. DeploymentEnvironmentKey. String("prod"))
tp:= sdktrace. NewTracerProvider(sdktrace. WithBatcher(exp), sdktrace. WithResource(res), sdktrace. WithSampler(sdktrace. ParentBased(sdktrace. TraceIDRatioBased(0. 05))))
otel. SetTracerProvider(tp)

12) Asinhronchina: filas, pneus, cron

O PRODUCER/CONSUMER está conectado através de 'links' (as mensagens têm seu próprio ciclo de vida).
Explore o contexto em cabeçalhos de mensagem ('traceparent '/' baggage').
Se você tiver um batch-consumo, crie um span por mensagem ou agregue com o atributo 'messaging. batch. size`.
Para cron/jobs: novo trace para iniciar + links para eventos primários (se houver).

13) Baggage e meta

Guarde o mínimo de chaves estáveis ('tenant _ id', 'region', 'vip _ tier') em baggage; proíba o PII.
Navegue através do gateway/gateway-logger para adicionar as métricas por segmento.

14) Integração com lançamentos e SLO-gating

Etapas de canarinho → verifique 'traces _ spanmetrics _' em rotas/segmentos de yuse.
Em caso de degradação (5xx/p95) - Auto-pare e recall (Argo Rollouts AnalysisTemplate + PromQL).
As cópias de métricas levam diretamente às pistas «ruins» do intervalo de lançamento.

15) Limites e desempenho

Ограничивайте: `OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT`, `OTEL_SPAN_EVENT_COUNT_LIMIT`, `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT`.
Samplie exceções/stacktrace por probabilidade/frequência.
Processador Batch em SDK e Colector; mantenha as filas para não perder as pistas nas subidas.

16) Compatibilidade e migração

Apresentadores: Use o W3C; suporte B3/X-Ray durante a migração.
Exportação: OTLP → APM (Jaeger/Tempo/Elastic/X-Ray etc.).
Versões estáveis semconv - Fixe 'schemaUrl' e planeje upgrades.

17) Anti-pattern

Alta cardealidade de atributos ('user _ id' em label, chaves dinâmicas).
Não há correlação sem 'trace _ id'.
Exportar diretamente de aplicativos para APM online (sem gateway, sem TLS/mTLS).
Recolher «apenas» 100% na venda é caro e sem sentido.
Dampas de consulta SQL com dados do usuário em 'db. statement`.
Nome de serviço/versão incoerente - as métricas «se desfazem».

18) Folha de cheque de implementação (0-45 dias)

0-10 dias

Ativar SDK/instalação automática em 2-3 serviços críticos.
Personalizar Agente (DaemonSet) + Gateway (Deployment), OTLP 4317/4318 com TLS.
Adicionar 'service. name`, `service. version`, `deployment. O environment está por todo o lado.

11 a 25 dias

Tail-sampling para erros/latência/rotas» monetárias».
SpanMetrics → Prometheus, incluir Exemplars e dashboard RED/SLO.
Encorajar o W3C através da entrada API/NGINX/mesh; correlação.

26-45 dias

Cobrir filas/BD/dinheiro; links para async.
Políticas de Edição PII no Colector; limites de atributos no SDK.
Integrar lançamentos SLO-gating e auto-revezamento.

19) Métricas de maturidade

A cobertura dos pedidos de rastreamento de entrada ≥ de 95% (considerando sampling head/tail).
A proporção de métricas com Excempars ≥ de 80%.
Tempo RCA «de métrica para pista» ≤ 2 min (p50).
0 vazamentos de PII em atributos/eventos (scanner).
Todos os serviços têm 'service. name/version/entronment 'e semântica coerente.

20) Aplicativos: fatias úteis

nginx proxy_set_header traceparent $http_traceparent;
proxy_set_header tracestate $http_tracestate;
proxy_set_header baggage   $http_baggage;

histogram_quantile(0. 95, sum(rate(traces_spanmetrics_duration_bucket{route="/withdraw"}[5m])) by (le))

Policy: proibição de atributos PII (pseudo-linter)

yaml forbid_attributes:
- user. email
- payment. card
- personal.

21) Conclusão

Transforma a observabilidade em um circuito normalizado e controlado, como semântica unificada, encorajamento seguro, sampling inteligente e forte correlação com métricas e logs. Construa o agente + gateway, adicione tail-sampling, spanmetrics e Excempars, acompanhe o PII e a vitalidade - e o rastreamento será uma ferramenta não só para depuração, mas também para soluções automatizadas SRE/Release, reduzindo MTTR e riscos a cada lançamento.