Trace Sampling no Node.js controla quais traces são registrados e exportados em sistemas observáveis. Capturar 100% das requisições pode ser útil em desenvolvimento, mas costuma gerar custo, volume e cardinalidade excessivos em produção.
O objetivo do sampling é preservar sinais úteis sem coletar tudo indiscriminadamente. Uma estratégia adequada mantém erros, operações lentas e amostras representativas do tráfego normal.
Head sampling
A decisão é tomada no início do trace, antes de conhecer o resultado.
import { TraceIdRatioBasedSampler } from '@opentelemetry/sdk-trace-base';
const sampler = new TraceIdRatioBasedSampler(0.1);Nesse exemplo, aproximadamente 10% dos traces são amostrados. A decisão é determinística pelo trace ID, o que ajuda serviços diferentes a manter a mesma escolha.
Parent-based sampling
Serviços downstream devem respeitar a decisão recebida do serviço pai. Isso evita traces fragmentados.
import {
ParentBasedSampler,
TraceIdRatioBasedSampler
} from '@opentelemetry/sdk-trace-base';
const sampler = new ParentBasedSampler({
root: new TraceIdRatioBasedSampler(0.1)
});Tail sampling
A decisão ocorre depois que spans foram coletados. Assim, o sistema pode manter traces com erro, alta latência ou atributos específicos. Essa abordagem normalmente exige um collector com buffer e mais recursos.
Preservando erros
Uma política útil mantém todos os traces com status de erro e amostra apenas uma parte dos sucessos. Isso melhora diagnóstico sem multiplicar custo.
Latência
Traces acima de um limite podem ser mantidos integralmente. Use percentis e SLOs para definir o que é “lento”, em vez de um valor arbitrário.
Rotas de baixo volume
Uma taxa global pode apagar operações raras. Para rotas críticas com pouco tráfego, estabeleça uma amostragem mínima ou regra dedicada.
Não use dados sensíveis
Sampling não é mecanismo de privacidade. Mesmo um trace raro pode conter informação pessoal. Redija headers, tokens, payloads e identificadores sensíveis antes da exportação.
Baggage e atributos
Propague apenas contexto necessário. Baggage viaja entre serviços e pode aumentar headers. Use atributos de baixa cardinalidade para políticas de sampling.
Consistência entre serviços
O header traceparent carrega a decisão sampled. Proxies e gateways devem preservar o contexto. Consulte API Gateway no Node.js.
Collector
O OpenTelemetry Collector pode receber OTLP, aplicar processamento e encaminhar dados. Tail sampling no collector centraliza políticas, mas exige memória suficiente para traces em andamento.
Exemplo de políticas
- 100% dos erros;
- 100% das requisições acima de dois segundos;
- 100% de operações administrativas;
- 10% do tráfego normal;
- 1% de endpoints de altíssimo volume.
Dimensionamento
Meça spans por trace, bytes por span, taxa de requisições e retenção. O custo depende do volume exportado, do backend e do número de atributos.
Observabilidade do sampling
Monitore:
- traces recebidos e exportados;
- taxa efetiva por serviço;
- itens descartados por memória;
- decisões por política;
- atraso do collector;
- erros de exportação.
Testes
Gere traces de sucesso, erro e alta latência. Confirme que a política mantém os casos importantes e que serviços filhos respeitam o parent.
Erros comuns
- usar 100% em produção sem estimar custo;
- amostrar cada serviço independentemente;
- perder rotas raras;
- fazer tail sampling sem memória suficiente;
- usar atributos de alta cardinalidade;
- acreditar que sampling protege dados sensíveis.
Conclusão
Trace Sampling no Node.js equilibra diagnóstico e custo. Head sampling é simples e previsível; tail sampling permite selecionar erros e latências depois de observar o trace completo.
Comece com parent-based ratio sampling, preserve erros e ajuste com métricas reais. Leia OpenTelemetry no Node.js, a documentação de sampling do OpenTelemetry e a documentação do Collector.
