Traces distribuídos

Como o Dodo Aegies rastreia requisições de ponta a ponta em múltiplos serviços e linguagens.

O que são traces distribuídos

Em uma arquitetura de microsserviços, uma única ação do usuário pode atravessar dezenas de serviços. Um trace distribuído captura toda essa jornada, unificando spans de serviços escritos em linguagens diferentes, rodando em hosts diferentes, em um único gráfico de causalidade.

Usuário clica "Finalizar compra"
  └── api-gateway           [5ms]
        └── checkout-service [380ms]
              ├── user-service       [12ms]
              ├── inventory-service  [290ms]  ← lento
              │     └── postgres     [275ms]  ← causa raiz
              └── payment-service    [45ms]

Context propagation

O Aegies usa o padrão W3C TraceContext (traceparent header) para propagar o trace_id entre serviços. Isso acontece automaticamente quando você usa o SDK:

Serviço A (Node.js) → Serviço B (Python)

// Serviço A — o SDK injeta automaticamente o header traceparent
const response = await fetch('http://inventory-service/reserve', {
  method: 'POST',
  body: JSON.stringify({ itemId }),
});

# Serviço B — o SDK extrai automaticamente o traceparent
from dodo_aegies import aegies
# Nenhuma configuração adicional — o span é automaticamente filho do trace de A

Para serviços que já usam OpenTelemetry, basta apontar o exporter para o Aegies — todos os traces existentes serão importados e exibidos normalmente.

Baggage

O baggage permite propagar metadados customizados ao longo do trace sem ter que passar manualmente em cada chamada:

aegies.setBaggage('user.tier', 'enterprise');
aegies.setBaggage('feature.flag', 'new-checkout-v2');

O baggage fica disponível em todos os spans descendentes e aparece no trace para facilitar a segmentação por cliente, feature flag ou tenant.

Sampling

O Aegies coleta 100% dos traces por padrão — sem amostragem. Isso garante que nenhum incidente seja perdido por má sorte na amostragem.

Para organizações com altíssimo volume, é possível configurar tail-based sampling: o Aegies decide manter ou descartar o trace depois de coletá-lo, priorizando traces com erro, latência acima do p95 ou span de banco de dados lento:

aegies.init({
  sampling: {
    strategy: 'tail',
    alwaysKeep: ['error', 'slow', 'db-slow'],
    rateForNormal: 0.1,  // 10% dos traces normais
  },
});

Atributos de span recomendados

Adicionar atributos aos spans melhora a filtragem e a análise de causa raiz:

span.setAttribute('user.id', userId);
span.setAttribute('tenant.id', tenantId);
span.setAttribute('db.statement', query);  // automaticamente mascarado
span.setAttribute('http.route', '/api/orders/:id');
span.setAttribute('messaging.system', 'kafka');
span.setAttribute('messaging.destination', 'orders-topic');

O Aegies segue as convenções semânticas do OpenTelemetry para nomear atributos, garantindo compatibilidade com ferramentas do ecossistema.

Filtrando e pesquisando traces

Na UI do Aegies você pode filtrar traces por:

• Serviço e endpoint — service:payments-api route:/api/checkout
• Status — status:error
• Latência — duration:>500ms
• Atributo customizado — user.tier:enterprise
• Período — últimos 15 minutos, 1 hora, 24 horas ou range customizado

Trace-to-log e Trace-to-metric

O Aegies correlaciona traces com logs e métricas automaticamente via trace_id:

• Trace → Logs: ao abrir um trace, veja todos os logs emitidos durante aquela requisição
• Trace → Profiling: veja o perfil de CPU do host durante o span mais lento
• Trace → Deploy: veja se houve deploy ou mudança de config próxima ao horário do trace

Próximos passos

• APM — métricas de latência, flame graphs e profiling
• Integrações — configurar exporters OpenTelemetry
• Motor de IA — como o Aegies usa traces para gerar patches