Observabilidade: logs, métricas e traces na prática

O cliente liga dizendo que o pedido não foi gravado. O painel de monitoramento está todo verde: servidor de pé, CPU tranquila, banco respondendo. Alguém abre o servidor, procura no log por uma palavra qualquer, encontra dez mil linhas sem contexto e, uma hora depois, a resposta oficial é "não conseguimos reproduzir".

Esse é o sintoma clássico de um sistema monitorado, mas não observável. A diferença não é semântica. Ela define se a sua equipe descobre o problema pelo cliente ou antes dele, e se o diagnóstico leva minutos ou uma tarde inteira. A seguir, como instrumentar um sistema de forma que ele responda perguntas que ninguém previu.

Monitoramento diz que caiu. Observabilidade diz por quê

Monitoramento responde perguntas que você já sabia fazer: o servidor está no ar? A fila passou de um limite? O disco está enchendo? São verificações definidas com antecedência, e funcionam bem para falhas conhecidas.

Observabilidade é a capacidade de entender o estado interno do sistema a partir do que ele emite, inclusive diante de uma falha que ninguém imaginou. "Por que só os pedidos de clientes da filial de Caxias estão lentos desde ontem à tarde?" não é uma pergunta que alguém configura num painel. Ou os dados permitem respondê-la, ou não permitem.

Na prática, observabilidade se apoia em três tipos de sinal:

• Logs: o registro de eventos discretos, com detalhe. "Pedido 4821 rejeitado: CNPJ sem inscrição estadual."
• Métricas: números agregados ao longo do tempo. Requisições por minuto, tempo de resposta, erros por tipo.
• Traces: o caminho de uma requisição específica por todos os componentes que ela tocou, com o tempo gasto em cada um.

Nenhum dos três basta sozinho. Métrica mostra que algo piorou; trace mostra onde; log mostra por quê. O valor está em conseguir pular de um para o outro.

Logs estruturados e correlação de requisições

O log típico de um sistema legado é uma frase: Erro ao processar pedido do cliente. Qual pedido? Qual cliente? Em qual requisição? Com qual versão do sistema?

Log estruturado troca a frase por um registro com campos: nível, mensagem, identificador do pedido, identificador do cliente (ou do tenant, num SaaS), versão da aplicação, nome do serviço e, principalmente, o identificador de correlação da requisição. Em vez de procurar texto, você filtra: todos os erros do cliente X na última hora, agrupados por tipo.

O identificador de correlação é o que dá sentido ao conjunto. Ele nasce quando a requisição entra no sistema e acompanha tudo o que acontece por causa dela: a chamada à API, a gravação no banco, a mensagem publicada na fila, o processamento assíncrono que roda dez segundos depois. Sem ele, cada linha de log é uma ilha.

Alguns cuidados que fazem diferença:

• Níveis com critério. Erro é algo que exige ação. Se o log de erro tem centenas de entradas por hora que ninguém olha, ele virou ruído e o erro real vai passar despercebido.
• Nada de dado pessoal ou segredo no log. Senha, token, número de cartão, CPF completo e dados de saúde não entram. Log costuma ter controle de acesso mais frouxo que o banco, e isso é um problema de segurança e de LGPD.
• Log centralizado. Log espalhado no disco de cada servidor desaparece quando o servidor é recriado. Ele precisa ir para um lugar onde possa ser pesquisado junto.

Métricas que representam a experiência do usuário

O erro mais comum é medir o que é fácil em vez do que importa. CPU, memória e disco são úteis para capacidade, mas não dizem se o usuário está conseguindo trabalhar. Um sistema pode estar com CPU baixa e todos os pedidos falhando.

O ponto de partida são os indicadores de nível de serviço (SLIs), definidos a partir da jornada do usuário:

• Proporção de requisições de emissão de pedido que terminam com sucesso.
• Tempo de resposta da tela de consulta de estoque, medido em percentis.
• Tempo entre o pagamento confirmado e a nota fiscal emitida.
• Proporção de integrações com o ERP processadas sem reprocessamento manual.

Sobre cada indicador, você define um objetivo (SLO): quanto daquele comportamento é aceitável dentro de uma janela de tempo. O objetivo é uma decisão de negócio, não técnica. Um relatório mensal pode tolerar lentidão que o caixa da loja não tolera.

Duas regras práticas. Primeiro, use percentis, não médias. A média esconde a cauda: se a maioria das requisições responde rápido e algumas levam uma eternidade, a média parece ótima enquanto uma parte dos usuários sofre. O percentil 95 ou 99 mostra o que os usuários mais prejudicados estão sentindo. Segundo, para cada serviço, acompanhe pelo menos volume, erros e latência. É o mínimo para perceber que algo mudou.

Quando um objetivo está definido, surge um conceito útil para o gestor: o orçamento de erro. Se o objetivo admite certa quantidade de falhas no mês e o sistema está consumindo esse espaço rápido demais, é hora de desacelerar entregas e investir em estabilidade. Isso transforma a velha discussão "entregar ou arrumar" em uma decisão com dados. É também a base de um SLA honesto, como explicamos em SLA de suporte e sustentação.

Tracing distribuído: seguindo uma requisição inteira

Num sistema com vários componentes, e isso inclui um monolito que chama ERP, gateway de pagamento e serviço de e-mail, a pergunta "onde foi parar o tempo?" raramente tem resposta óbvia.

O trace responde isso. Cada requisição recebe um identificador, e cada etapa dela vira um trecho (span) com início, fim e atributos: a consulta ao banco, a chamada HTTP ao ERP, a publicação na fila. O resultado é uma linha do tempo visual. Você enxerga, por exemplo, que a tela demora porque faz trinta consultas pequenas em sequência, ou que a lentidão está inteira na resposta da API de um parceiro.

O trace é especialmente valioso em três situações:

• Arquiteturas distribuídas. Com serviços separados, depurar sem tracing é arqueologia. É um dos custos que discutimos em monolito ou microsserviços.
• Integrações externas. Fica claro quando o problema é do seu lado e quando é do fornecedor, com evidência para cobrar.
• Diagnóstico de lentidão. Muitas vezes o trace sozinho revela consultas repetidas e chamadas desnecessárias. O método completo está em sistema lento: como diagnosticar.

Como guardar o trace de cada requisição sai caro em volume, usa-se amostragem: guarda-se uma fração das requisições normais e, idealmente, todas as que deram erro ou foram lentas.

Instrumentação com padrão aberto

Instrumentar é colocar no código o que gera logs, métricas e traces. A decisão mais importante aqui não é qual ferramenta de visualização usar, e sim como instrumentar sem se amarrar a ela.

O OpenTelemetry é hoje o padrão aberto para isso, mantido pela comunidade da Cloud Native Computing Foundation. Ele define uma forma única de gerar e transportar telemetria, com bibliotecas para as linguagens mais usadas e instrumentação automática para frameworks web, bancos de dados e clientes HTTP. O código emite dados no formato padrão, e um componente chamado coletor encaminha para o destino que você escolher: uma ferramenta comercial, uma solução de código aberto ou o serviço do seu provedor de nuvem.

A consequência prática é poder trocar de fornecedor de observabilidade sem reescrever a instrumentação. Se o custo subir ou a ferramenta deixar de atender, a mudança fica no coletor, não em centenas de arquivos.

Uma divisão sensata de trabalho:

• Instrumentação automática cobre o básico: requisições HTTP, consultas ao banco, chamadas externas.
• Instrumentação manual entra nos pontos de negócio: "pedido aprovado", "nota emitida", "integração com o ERP reprocessada". É aqui que a telemetria começa a falar a língua da empresa.
• Atributos consistentes em todos os sinais: o mesmo nome para cliente, tenant, versão e ambiente. Sem isso, cruzar log com trace vira trabalho manual.

Alertas que merecem acordar alguém

Excesso de alerta é tão ruim quanto nenhum. Quando o celular do plantão toca a noite toda por coisas que se resolvem sozinhas, a equipe aprende a ignorar, e o alerta que importa vai junto.

Um bom critério: alerta que acorda alguém precisa indicar impacto no usuário e exigir ação humana agora. Todo o resto vira aviso para o horário comercial ou vira apenas um gráfico.

Na prática:

• Alerte sobre sintomas, não sobre causas. "A taxa de erro na emissão de pedidos subiu" é acionável. "A CPU passou de um limite" nem sempre é problema.
• Alerte sobre consumo do orçamento de erro, em vez de disparar a cada falha isolada.
• Cada alerta tem um procedimento. Um texto curto dizendo o que verificar primeiro, onde olhar e quem escalar. Alerta sem procedimento transfere o problema para quem está com sono.
• Revise periodicamente. Alerta que disparou e ninguém agiu deve ser ajustado ou removido.

Não esqueça do alerta mais básico e mais esquecido: uma verificação externa, de fora da sua infraestrutura, que simula um usuário acessando o sistema. Se a nuvem inteira cair, o monitoramento interno cai junto e não avisa ninguém.

Controlando volume e custo de telemetria

Observabilidade gera muito dado, e dado armazenado tem custo. Sistemas que logam tudo, em nível de depuração, com retenção indefinida, acabam gastando mais com telemetria do que parece razoável, e ainda assim ninguém acha nada no meio do volume.

O controle vem de decisões simples:

• Nível de log adequado por ambiente. Depuração em desenvolvimento, informação e erro em produção.
• Amostragem de traces, priorizando erros e requisições lentas.
• Cardinalidade de métricas sob controle. Usar o identificador do usuário ou do pedido como rótulo de métrica multiplica séries sem limite. Esse tipo de detalhe vai para log e trace, não para métrica.
• Retenção por tipo de dado. Log detalhado por pouco tempo, métricas agregadas por mais tempo, registros de auditoria pelo prazo que a regra de negócio ou a lei exigir.

Se a conta de nuvem já é uma preocupação, a telemetria é um dos itens a revisar, junto com os outros pontos de como reduzir custos de nuvem.

Quando faz sentido investir, e quando ainda não

Nem todo sistema precisa de tracing distribuído no primeiro dia. Uma aplicação interna, com poucos usuários e um único processo, se resolve bem com logs estruturados centralizados, métricas básicas e uma verificação externa de disponibilidade.

O investimento maior se justifica quando:

• o sistema é crítico para faturamento, atendimento ou produção;
• há integrações com parceiros e alguém precisa provar de quem é a falha;
• existem vários componentes ou serviços;
• o cliente costuma descobrir o problema antes da equipe;
• existe um SLA a cumprir e ninguém consegue medir se ele está sendo cumprido.

Como medir se a observabilidade está funcionando

• Quem descobre o incidente primeiro: a equipe, por alerta, ou o cliente, por telefone.
• Tempo até entender a causa, não só até restaurar o serviço.
• Proporção de alertas que exigiram ação. Muitos alertas sem ação indicam ruído.
• Incidentes cujo diagnóstico dependeu de acesso direto ao servidor. O ideal é que isso vire exceção.

Checklist rápido

• Logs estruturados, centralizados e sem dados sensíveis.
• Identificador de correlação atravessando requisições, filas e tarefas assíncronas.
• Indicadores e objetivos definidos a partir das jornadas críticas do usuário.
• Latência medida em percentis.
• Tracing nos fluxos com integrações e múltiplos componentes.
• Instrumentação com OpenTelemetry, sem dependência de fornecedor.
• Alertas por sintoma, cada um com procedimento.
• Verificação externa de disponibilidade.
• Política de amostragem e retenção definida.

Enxergando o sistema por dentro

Na Pervian Tech, observabilidade faz parte do nosso trabalho de cloud e DevOps: instrumentação com padrão aberto, painéis organizados pelas jornadas que importam para o seu negócio e alertas desenhados para chamar alguém só quando é preciso. Pode ser num sistema que construímos ou num que você já tem em produção.

Cada ambiente é diferente, então o trabalho é sob medida e o investimento é definido sob consulta, depois de um diagnóstico inicial gratuito do que o seu sistema já emite e do que falta. Se a sua equipe ainda descobre os problemas pelo cliente, conte como está hoje.