Traces

O Guara Cloud captura traces distribuídos de todos os serviços rodando na plataforma — sem exigir uma única linha de instrumentação na sua aplicação.

Como funciona

O tracing no Guara Cloud é construído sobre três componentes:

• O Beyla roda como um daemon baseado em eBPF em cada node e descobre HTTP, gRPC, Redis, NATS, Postgres e outros protocolos no nível do kernel. Sem SDK para instalar.
• Coletores OpenTelemetry recebem os spans do Beyla, fazem o batching e encaminham tudo para o Tempo.
• O Grafana Tempo armazena os traces e os disponibiliza para o dashboard e para a API consultar por trace ID, janela de tempo, status e duração mínima.

Com isso você tem traces ponta-a-ponta de chamadas internas entre serviços e de requisições externas, sem mudar a aplicação.

Visualização cross-service

Quando uma única requisição passa por vários serviços, a página de detalhe do trace mostra tudo numa imagem unificada com três visões coordenadas:

• Mini mapa de serviços no topo — todo serviço que participou do trace, desenhado como um pequeno grafo. Clique em um node para filtrar o waterfall apenas para spans de ou para aquele serviço. Serviços reais são clicáveis e levam à página de detalhe; sentinelas Internet e External (veja abaixo) propositalmente não são navegáveis.
• Faixa de participantes — chips compactos listando todo serviço no trace, mais sentinelas de Internet / External. Útil quando o mapa fica grande demais para olhar de relance.
• Waterfall agrupado por faixa de serviço — em vez de uma lista plana, os spans caem em faixas com o nome do serviço a que pertencem. Spans server, internal, producer e consumer ficam na faixa do próprio serviço; spans client são atribuídos ao serviço de destino que está sendo chamado. Isso significa que toda chamada ao payment-api se acumula numa única faixa, independente de quem iniciou.

A lista de traces também mostra um chip de serviços envolvidos em cada linha — contagem de serviços reais únicos tocados pelo trace, para você identificar requisições complexas de relance.

Sentinelas de Internet e External

Um trace muitas vezes toca mais que só os seus serviços — chamadas a APIs de terceiros, requisições vindo da internet pública, chamadas a um banco gerenciado fora do projeto. Dois nodes sintéticos tornam isso visível sem poluir a lista de participantes com uma entrada por host:

• Internet — representa tráfego originado de fora do seu projeto (tipicamente requisições de usuários finais entrando pelo edge). Uma sentinela por trace; spans raiz sem um serviço pai pendem daqui.
• External (<host>) — representa um destino de saída fora do seu projeto. Uma sentinela por host de destino único. Chamadas a api.stripe.com, mongodb.atlas.cloud, etc. ficam agrupadas sob suas respectivas sentinelas External.

Sentinelas aparecem como nodes no mini mapa e como faixas no waterfall, com tratamento visual distinto para que você identifique de relance onde está a fronteira do seu projeto.

Visualizando traces no dashboard

Abra um serviço no dashboard e vá para a aba Traces. Você pode:

• Filtrar por janela de tempo, status (ok / error) e duração mínima.
• Clicar em um trace para ver o waterfall completo de spans entre serviços, com tempo por span e atributos de erro quando existirem.
• Clicar em qualquer span do waterfall para ver seus atributos completos e saltar para o serviço relacionado.
• Saltar de um trace para os logs e métricas relacionados ao mesmo serviço e janela.

Visualizando traces pela CLI

Os mesmos dados estão disponíveis no terminal — útil quando você está investigando direto de uma sessão de shell ou montando checks em CI:

• guara services traces list — lista os traces recentes com filtros equivalentes aos do dashboard.
• guara services traces get <traceId> — renderiza o waterfall completo direto no terminal, com spans em erro destacados em vermelho.

Cron workers nos traces

Disparos de cron worker são instrumentados com seus próprios spans e propagam o header W3C traceparent para o destino. Um disparo HTTP agendado para um dos seus serviços aparece, portanto, como um único trace cobrindo o span do cron, o span da requisição HTTP no serviço receptor e qualquer trabalho que aquele serviço faz como consequência. Veja Cron Workers para detalhes.

Pela CLI

Dois comandos expõem os mesmos dados no terminal — combine-os quando estiver investigando direto do shell ou montando checks em CI.

Tail ao vivo

guara services traces list --watch é um feed ao vivo append-only — cada tick adiciona apenas os traces que ainda não viu, então você pode deixar o comando rodando e tratar o terminal como um tail. Combine com --status error para esperar por falhas.

guara services traces list --watch
guara services traces list --watch --status error --min-duration-ms 500
guara services traces list --watch --interval 3 --service my-api

Saída de exemplo:

14:32:01  ● 124ms   GET /healthz                  → my-api          5 spans
14:32:02  ● 312ms   POST /orders                  → my-api          18 spans
14:32:04  ✕ 30001ms POST /webhooks/stripe         → payments-api    9 spans
14:32:05  ● 89ms    GET /users/me                 → my-api          4 spans
14:32:08  ● 451ms   POST /orders                  → my-api          22 spans

Verde ● para ok, vermelho ✕ para traces com pelo menos um span em erro. Cada linha é adicionada exatamente uma vez, mesmo que o trace continue na janela de polling.

Waterfall

guara services traces get <traceId> renderiza o waterfall completo direto no terminal — cada span em uma linha, posicionada pelo tempo de início, dimensionada pela duração e colorida pelo status. Encadeie a saída em less para navegar, ou use --errors para esmaecer spans sem erro durante a triagem.

guara services traces get 4f2ab91d
guara services traces get 4f2ab91d --errors --depth 3
guara services traces get 4f2ab91d --json | jq '.spans[] | select(.status == "error")'

Saída de exemplo (truncada, sem cor):

trace 4f2ab91d  ·  POST /webhooks/stripe  ·  30001ms  ·  ✕ error

  payments-api · POST /webhooks/stripe        ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇   30001ms  ✕
   payments-api · verifySignature              ▇                       18ms      ok
   payments-api · db.query                     ▇▇▇                     142ms     ok
   payments-api · stripe.events.dispatch       ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇       29800ms  ✕
    External (api.stripe.com) · POST /events   ▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇▇       29800ms  ✕

Sempre que você tiver um trace ID em mãos — copiado de um painel do Grafana, de uma linha de log ou de outra ferramenta — guara services traces get <trace-id> é o caminho mais rápido entre “algo falhou” e “este span exato deu timeout”.