Diagrama de arquitetura de observabilidade: logs, métricas e traces com OpenTelemetry

A maioria dos diagramas de arquitetura para nos serviços. O caminho da telemetria é desenhado depois, durante um incidente, por quem está tentando descobrir por que metade dos traces sumiu ou por que a conta de logs dobrou. Nessa hora, a resposta depende de detalhes que ninguém escreveu: qual componente faz amostragem, qual adiciona o nome do pod e o que acontece quando um backend fica lento.

Um diagrama de arquitetura de observabilidade mostra como logs, métricas e traces saem de cada serviço, onde são enriquecidos, amostrados e filtrados e onde terminam. Este artigo constrói um em torno do OpenTelemetry no Kubernetes, explica os padrões de agente e gateway por trás dele e lista o que rotular para que o diagrama continue útil na próxima queda.

Três sinais, três perguntas

Os três só são úteis juntos se compartilharem contexto. Um trace ID na linha de log, e o mesmo service.name e nome de pod em todos os sinais, permitem pular de um alerta para o span lento e daí para a linha de log que o explica. A arquitetura precisa manter esse contexto intacto.

As peças

OTLP é o protocolo do OpenTelemetry para os três sinais. A especificação define as portas padrão: 4317 para OTLP sobre gRPC e 4318 para OTLP sobre HTTP.

SDKs e instrumentação automática rodam dentro de cada serviço e exportam OTLP. Aponte-os para um Collector local em vez de um fornecedor, para que mudanças de roteamento não exijam novo deploy.

O Collector é um único binário com pipelines por sinal: receivers recebem os dados, processors os modificam e exporters os enviam adiante. A documentação de implantação descreve duas formas principais de executá-lo:

• Agente. Um Collector roda ao lado da aplicação, como sidecar ou como DaemonSet com um pod por nó. No Kubernetes, o agente também é onde trabalham os componentes do Kubernetes: o Kubernetes Attributes Processor adiciona nomes de pod, namespace e deployment, o Filelog Receiver acompanha o stdout e o stderr dos contêineres e o Kubeletstats Receiver coleta métricas de nós e pods.
• Gateway. Um ou mais Collectors rodam como um serviço independente, normalmente um ponto de extremidade por cluster, data center ou região. O gateway é o lugar das decisões que você quer tomar uma vez só: amostragem, filtragem de atributos sensíveis, guarda das credenciais dos backends e envio para mais de um backend.

Head sampling ou tail sampling

Traces são o sinal caro, então a maioria das equipes faz amostragem. O head sampling decide quando o trace começa, por exemplo mantendo 10%. É barato, mas não consegue guardar um trace porque ele falhou depois. O tail sampling decide depois de ver todos ou quase todos os spans de um trace, então consegue guardar cada erro e cada requisição lenta.

O tail sampling tem um custo estrutural: todos os spans de um trace precisam chegar ao mesmo Collector. Atrás de um balanceador round-robin, isso não acontece. O padrão de gateway resolve isso com dois níveis: o primeiro executa o load-balancing exporter com o trace ID como chave de roteamento e o segundo executa o tail sampling processor. São duas caixas no diagrama, e vale a pena mostrar as duas.

O exemplo: uma loja no Kubernetes

A loja roda três Deployments em um namespace shop: web, checkout-api e payments-worker, cada um com o SDK do OpenTelemetry. O namespace observability abriga o pipeline: um DaemonSet otel-agent, um Deployment otel-lb que roteia os spans por trace ID e um Deployment otel-sampler que aplica a política de tail sampling. Métricas, traces e logs vão cada um para o seu armazenamento, e regras de alerta rodam sobre as métricas.

Como ler:

• À esquerda, os serviços. Cada Deployment exporta traces, métricas e logs via OTLP/gRPC na porta 4317 para o agente do seu nó. A conexão tracejada é o stdout dos contêineres, que o agente lê no nó em vez de receber pela rede.
• No meio, o agente. O agente adiciona metadados do Kubernetes a tudo e então envia métricas e logs direto para seus armazenamentos, e os traces para o gateway.
• No meio, o gateway. otel-lb roteia cada span por trace ID, para que todos os spans de um trace cheguem ao mesmo pod de otel-sampler, que guarda erros e traces lentos e amostra o resto.
• À direita, armazenamento e alertas. Cada sinal tem seu próprio backend. As regras de alerta leem as métricas e acionam quem estiver de plantão.
• O bloco Markdown registra a política de amostragem e a única regra que todo pipeline segue: o memory limiter primeiro.

O que rotular

• Protocolo e porta em cada salto. OTLP/gRPC 4317 ou OTLP/HTTP 4318, e o formato de exportação para cada backend.
• Quais sinais passam em cada conexão. Um pipeline raramente leva os três do mesmo jeito.
• Onde a amostragem acontece, e com qual política. Escreva os números; só "amostrado" convida a suposições erradas.
• Onde os dados são enriquecidos ou mascarados. Metadados do Kubernetes no agente; remoção de tokens e dados pessoais no gateway.
• Retenção por backend. Ela explica o custo e o que uma investigação ainda consegue encontrar.
• Comportamento em falhas. Filas, novas tentativas e o que é descartado quando um backend cai.

Erros comuns

• SDKs exportando direto para um fornecedor. Toda mudança de roteamento ou de credenciais vira um deploy, e não há onde filtrar os dados antes que eles saiam.
• Tail sampling atrás de um balanceador simples. Os spans de um trace caem em Collectors diferentes, e as decisões de amostragem são tomadas sobre fragmentos.
• Nenhum memory limiter. A documentação de configuração inclui um processor memory_limiter; coloque-o em primeiro lugar em cada pipeline para que, num pico, o Collector recuse dados em vez de ficar sem memória.
• Rótulos de métricas com alta cardinalidade. Um ID de usuário ou de requisição como rótulo de métrica multiplica as séries temporais. Coloque-o nos spans e nos logs.
• Um pipeline sem monitoramento. O Collector expõe as próprias métricas, por padrão na porta 8888, como descrito na documentação de telemetria interna. Crie alertas para exportações com falha, ou você vai descobrir a perda de dados durante o incidente que precisava deles.

Para o cluster em si, o diagrama de arquitetura do Kubernetes cobre o plano de controle, os nós e as cargas de trabalho, e o diagrama de arquitetura de microsserviços cobre os serviços que este pipeline observa.

Monte no Archboard

1. Entre com Google ou GitHub e crie um diagrama.
2. Do pack Kubernetes, adicione duas molduras Namespace, shop e observability. Coloque um Deployment para cada serviço em shop.
3. Em observability, adicione um DaemonSet para o agente e dois nós Deployment para os níveis de balanceamento e de amostragem.
4. Do pack DevOps, adicione nós Métricas, Rastreamentos e Registros para os backends e um nó Alerta para os alertas.
5. Conecte-os e rotule cada conexão com os sinais e o protocolo, por exemplo "OTLP/gRPC 4317". Deixe tracejada a conexão dos logs de contêiner.
6. Adicione um bloco Markdown do pack Básico com a política de amostragem.

O exemplo usa 13 nós de diagrama e fica dentro do plano Free. Se os seus serviços já rodam no Kubernetes, a ferramenta Kubernetes YAML para diagrama transforma os manifestos num primeiro rascunho da metade esquerda.

Perguntas frequentes

Preciso de um Collector em gateway ou bastam os agentes? Só agentes funcionam em instalações pequenas. Adicione um gateway quando precisar de tail sampling, de um lugar único para credenciais e filtragem ou de vários backends; o agente passa então a encaminhar os dados para ele.

Os logs também devem passar pelo Collector? Podem. O Filelog Receiver do agente lê os logs dos contêineres, adiciona os mesmos metadados do Kubernetes que traces e métricas recebem e permite filtrar antes do armazenamento. Muitas equipes levam os logs para o Collector por último, depois de traces e métricas.

O head sampling chega a ser suficiente? Sim, quando o tráfego é baixo ou todos os traces são parecidos. Se você precisa de cada erro e cada requisição lenta, use tail sampling e desenhe os dois níveis de gateway que ele exige.

Onde ficam painéis e alertas no diagrama? Ao lado do armazenamento que consultam. Regras de alerta sobre métricas fazem parte da arquitetura: são elas que decidem quem é acordado.

Como mantenho este diagrama atualizado? Altere-o no mesmo pull request da configuração do Collector e coloque um link para ele no runbook. Veja diagramas de arquitetura que não ficam desatualizados.

Comece grátis — um assento, sem cartão de crédito.