Kit inicial de observabilidade em produção para monitoramento desde o primeiro dia

O que quebra primeiro quando um app novo recebe usuários reais

A primeira coisa que quebra raramente é o app inteiro. Normalmente é um único passo que de repente fica muito ocupado, uma query que parecia ok nos testes ou uma dependência que começa a dar timeout. Usuários reais trazem variedade: celulares mais lentos, redes instáveis, entradas estranhas e picos de tráfego em momentos inconvenientes.

Quando alguém diz “está lento”, pode querer dizer coisas bem diferentes. A página pode demorar demais para carregar, interações podem travar, uma chamada de API pode estar dando timeout, jobs em background podem estar se acumulando, ou um serviço externo pode estar arrastando tudo.

Por isso você precisa de sinais antes de precisar de dashboards. No primeiro dia, você não precisa de gráficos perfeitos para cada endpoint. Precisa de logs, métricas e traces suficientes para responder a uma pergunta rapidamente: onde o tempo está sendo gasto?

Há também um risco real em instrumentar demais cedo. Muitos eventos geram ruído, custam dinheiro e podem até deixar o app mais lento. Pior: equipes param de confiar na telemetria porque ela parece bagunçada e inconsistente.

Uma meta realista para o primeiro dia é simples: quando chegar um relato de “está lento”, você consegue achar o passo lento em menos de 15 minutos. Deve ser possível dizer se o gargalo está na renderização cliente, no handler da API e suas dependências, no banco/cache, ou em um worker em background ou serviço externo.

Exemplo: um novo fluxo de checkout parece lento. Mesmo sem uma pilha enorme de ferramentas, você quer poder dizer: “95% do tempo está em chamadas ao provedor de pagamento” ou “a query do carrinho está escaneando muitas linhas”. Se você constrói apps rápido com ferramentas como Koder.ai, essa linha de base do primeiro dia importa ainda mais, porque velocidade de entrega só ajuda se você também consegue debugar rápido.

Logs vs métricas vs traces em linguagem simples

Um bom kit inicial de observabilidade em produção usa três “visões” diferentes do mesmo app, porque cada uma responde a uma pergunta distinta.

Logs são a história. Eles dizem o que aconteceu para uma requisição, um usuário ou um job em background. Uma linha de log pode dizer “pagamento falhou para pedido 123” ou “timeout no DB após 2s”, além de detalhes como request ID, user ID e a mensagem de erro. Quando alguém relata um problema pontual, logs costumam ser a forma mais rápida de confirmar que aconteceu e quem foi afetado.

Métricas são o placar. São números que você pode trendear e alertar: taxa de requisições, taxa de erros, percentis de latência, CPU, profundidade de fila. Métricas dizem se algo é raro ou generalizado e se está piorando. Se a latência subiu para todos às 10:05, as métricas vão mostrar isso.

Traces são o mapa. Um trace segue uma única requisição enquanto ela passa pelo sistema (web -> API -> banco -> serviço externo). Mostra onde o tempo é gasto, passo a passo. Isso importa porque “está lento” quase nunca é um grande mistério único. Geralmente é um salto lento.

Durante um incidente, um fluxo prático fica assim:

• Use métricas para confirmar o impacto (quantos usuários, quão grave, quando começou).
• Use traces para encontrar o passo mais lento (um gargalo que você pode agir).
• Use logs para explicar o gargalo (erros específicos, inputs ou casos de borda).

Uma regra simples: se você não consegue apontar um gargalo depois de alguns minutos, você não precisa de mais alertas. Você precisa de traces melhores e de IDs consistentes que conectem traces a logs.

Convenções do primeiro dia que evitam caos depois

A maioria dos incidentes “não encontramos” não vem da falta de dados. Acontecem porque a mesma coisa é registrada de forma diferente entre serviços. Algumas convenções compartilhadas no primeiro dia fazem logs, métricas e traces alinharem quando você precisa de respostas rápidas.

Comece escolhendo um nome de serviço por unidade deployável e mantenha-o estável. Se “checkout-api” vira “checkout” em metade dos dashboards, você perde histórico e quebra alerts. Faça o mesmo para labels de ambiente. Escolha um conjunto pequeno como prod e staging, e use-os em todo lugar.

Em seguida, torne cada requisição fácil de seguir. Gere um request ID na borda (API gateway, servidor web ou primeiro handler) e passe-o por chamadas HTTP, filas de mensagens e jobs em background. Se um ticket de suporte diz “estava lento às 10:42”, um único ID permite puxar os logs e o trace exatos sem adivinhar.

Um conjunto de convenções que funciona bem no primeiro dia:

• Identity: nome do serviço, ambiente, versão (ou SHA do build)
• Correlation: request ID propagado entre serviços e jobs
• Tags principais: rota (ou handler), método, status code e tenant/org ID se for multi-tenant
• Operações de tracing: nomeie operações por endpoints e jobs em background (não por nomes aleatórios de função)
• Consistência: um estilo de nomes e uma unidade de tempo para durações

Combine unidades de tempo cedo. Escolha milissegundos para latência de API e segundos para jobs mais longos, e mantenha isso. Unidades mistas criam gráficos que parecem ok mas contam a história errada.

Um exemplo concreto: se toda API loga duration_ms, route, status e request_id, então um relato como “checkout está lento para o tenant 418” vira um filtro rápido, não um debate sobre por onde começar.

Logging mínimo a adicionar no primeiro dia

Se você só fizer uma coisa no seu kit inicial de observabilidade em produção, torne os logs fáceis de buscar. Isso começa com logs estruturados (geralmente JSON) e os mesmos campos em todos os serviços. Logs em texto livre são ok para dev local, mas viram ruído quando há tráfego real, retries e múltiplas instâncias.

Uma boa regra: logue o que você realmente vai usar durante um incidente. A maioria das equipes precisa responder: Qual foi a requisição? Quem a fez? Onde falhou? O que tocou? Se uma linha de log não ajuda com uma dessas, provavelmente não deveria existir.

Para o primeiro dia, mantenha um conjunto pequeno e consistente de campos para filtrar e juntar eventos entre serviços:

• Timestamp, level e identidade do serviço (service name, version, environment)
• Correlação de requisição (request_id, trace_id se tiver)
• Quem/onde (user_id ou session_id, route, method)
• Resultado (status_code, duration_ms)
• Contexto de deployment (região/instância, release ou commit)

Quando um erro acontece, logue-o uma vez, com contexto. Inclua um tipo de erro (ou código), uma mensagem curta, stack trace para erros de servidor e a dependência upstream envolvida (por exemplo: postgres, payment provider, cache). Evite repetir o mesmo stack trace a cada retry. Em vez disso, anexe o request_id para seguir a cadeia.

Exemplo: um usuário relata que não consegue salvar configurações. Uma busca por request_id mostra um 500 em PATCH /settings, depois um timeout downstream para Postgres com duration_ms. Você não precisou do payload completo, só da rota, usuário/sessão e do nome da dependência.

Privacidade faz parte do logging, não é uma tarefa posterior. Não registre senhas, tokens, cabeçalhos de auth, bodies completos ou PII sensível. Se precisar identificar um usuário, logue um ID estável (ou um valor hash) em vez de emails ou telefones.

Se você constrói apps com Koder.ai (React, Go, Flutter), vale incluir esses campos em cada serviço gerado desde o início para não acabar “consertando logs” durante o primeiro incidente.

Métricas mínimas que pegam a maioria dos problemas em produção

Um bom kit inicial de observabilidade em produção começa com um conjunto pequeno de métricas que respondem rápido a uma pergunta: o sistema está saudável agora e, se não, onde está doendo?

Os sinais principais

A maioria dos problemas em produção aparece como um dos quatro “sinais principais”: latência (respostas lentas), tráfego (carga mudou), erros (algo falha) e saturação (um recurso compartilhado está no limite). Se você consegue ver esses quatro sinais por parte importante do seu app, dá para triager a maioria dos incidentes sem chutar.

Latência deve ser percentis, não médias. Acompanhe p50, p95 e p99 para ver quando um pequeno grupo de usuários está tendo uma má experiência. Para tráfego, comece com requests por segundo (ou jobs por minuto para workers). Para erros, separe 4xx vs 5xx: subida de 4xx costuma indicar mudança no cliente ou validação; subida de 5xx aponta para seu app ou dependências. Saturação é o sinal de “estamos ficando sem algo” (CPU, memória, conexões DB, backlog de fila).

Checklist de métricas por componente

Um conjunto mínimo que cobre a maioria dos apps:

• HTTP/API: requests por segundo, latência p50/p95/p99, taxa 4xx, taxa 5xx
• Banco de dados: latência de query (pelo menos p95), uso do pool de conexões (in-use vs max), timeouts, contagem de queries lentas
• Workers/filas: profundidade da fila, runtime de jobs p95, retries, contagem de dead-letter (ou jobs falhos)
• Recursos: CPU %, uso de memória, uso de disco (e I/O se isso te atrapalha), reinícios de container
• Saúde de deploy: versão atual, taxa de erro após deploy, loops de reinício (frequentemente o primeiro sinal de um release ruim)

Um exemplo concreto: se usuários relatam “está lento” e a p95 da API dispara enquanto o tráfego permanece estável, cheque saturação em seguida. Se o uso do pool do DB estiver perto do máximo e timeouts aumentarem, você encontrou um gargalo provável. Se o DB parece ok mas a profundidade da fila cresce rápido, trabalho em background pode estar disputando recursos compartilhados.

Se você constrói apps na Koder.ai, trate essa checklist como parte da definição de pronto do primeiro dia. É mais fácil adicionar essas métricas enquanto o app é pequeno do que durante o primeiro incidente real.

Tracing mínimo que torna “está lento” diagnosticável

Se um usuário diz “está lento”, logs costumam dizer o que aconteceu e métricas dizem com que frequência. Traces dizem para onde foi o tempo dentro de uma requisição. Essa única linha do tempo transforma uma queixa vaga em uma correção clara.

Comece no lado servidor. Instrumente requisições de entrada na borda do seu app (o primeiro handler que recebe a requisição) para que cada requisição possa gerar um trace. Tracing do lado cliente pode esperar.

Um bom trace de primeiro dia tem spans que mapeiam as partes que normalmente causam lentidão:

• Span do handler da requisição para toda a requisição
• Span de chamada ao banco para cada query ou transação
• Span de cache (get/set) quando você usa cache
• Span de chamada HTTP externa para cada dependência que você chama
• Span de job em background quando a requisição enfileira trabalho que você depende

Para tornar traces pesquisáveis e comparáveis, capture alguns atributos-chave e mantenha-os consistentes entre serviços.

Para o span de requisição de entrada, registre rota (use um template como /orders/:id, não a URL completa), método HTTP, status code e latência. Para spans de banco, registre o sistema DB (PostgreSQL, MySQL), tipo de operação (select, update) e o nome da tabela se for fácil adicionar. Para chamadas externas, registre o nome da dependência (payments, email, maps), host alvo e status.

A amostragem importa no primeiro dia, caso contrário custo e ruído crescem rápido. Use uma regra simples head-based: trace 100% dos erros e das requisições lentas (se seu SDK suportar) e amostre uma pequena porcentagem do tráfego normal (como 1–10%). Comece mais alto com pouco tráfego e reduza conforme o uso aumenta.

O que é “bom”: um trace onde você consegue ler a história de cima para baixo. Exemplo: GET /checkout demorou 2.4s, o banco gastou 120ms, cache 10ms e uma chamada externa de pagamento levou 2.1s com um retry. Agora você sabe que o problema é a dependência, não seu código. Isso é o núcleo de um kit inicial de observabilidade em produção.

Um fluxo simples de triagem para relatos de “está lento”

Quando alguém diz “está lento”, a vitória mais rápida é transformar essa sensação vaga em algumas perguntas concretas. Este fluxo de triagem do kit inicial funciona mesmo se seu app for novíssimo.

A triagem em 5 passos

Comece estreitando o problema, depois siga as evidências na ordem. Não pule direto para o banco.

1. Confirme o escopo. É um usuário, uma conta cliente, uma região ou todo mundo? Pergunte também: acontece no Wi‑Fi e em celular, e em mais de um navegador/dispositivo?
2. Verifique o que mudou primeiro. O volume de requisições aumentou, a taxa de erros subiu ou só a latência subiu? Um pico de tráfego costuma causar enfileiramento; subida de erros costuma indicar uma dependência quebrada.
3. Divida a lentidão por rota ou operação. Veja p95 de latência por endpoint (ou tipo de job) e encontre o pior. Se só uma rota está lenta, foque nela. Se todas as rotas estão mais lentas, pense em dependências compartilhadas ou capacidade.
4. Abra um trace para o caminho lento. Pegue um trace de uma requisição lenta e ordene os spans por duração. O objetivo é uma frase: “A maior parte do tempo está em X.”
5. Valide dependências e decida sobre rollback. Verifique saturação do banco, queries lentas, taxa de acerto do cache e tempos de resposta de terceiros. Se a lentidão começou logo após um deploy ou mudança de configuração, rollback costuma ser a ação mais segura.

Depois que estabilizar, faça uma pequena melhoria: escreva o que aconteceu e adicione um sinal ausente. Por exemplo, se você não conseguiu saber se a lentidão era só em uma região, adicione uma tag de região nas métricas de latência. Se viu um span de DB longo sem saber qual query, adicione labels de query com cuidado ou um campo “query name”.

Um exemplo rápido: se o p95 do checkout pula de 400 ms para 3 s e traces mostram um span de 2.4 s numa chamada de pagamento, você pode parar de debater o código e focar no provedor, retries e timeouts.

Verificações rápidas que você pode fazer em 5 minutos

Quando alguém diz “está lento”, você pode perder uma hora só para entender o que a pessoa quer dizer. Um kit inicial de observabilidade só é útil se ajudar a estreitar o problema rápido.

Comece com três perguntas de clarificação:

• Quem é afetado (um usuário, um segmento de cliente, todos)?
• Qual ação exata está lenta (carregamento de página, busca, checkout, login)?
• Desde quando começou (minutos atrás, depois de um deploy, desde esta manhã)?

Depois olhe alguns números que normalmente dizem para onde ir. Não procure o dashboard perfeito. Você quer sinais de “pior do que o normal”.

• Taxa de erro atual (picos de erro muitas vezes parecem lentidão aos usuários)
• p95 de latência para o endpoint afetado (não a média)
• Saturação: CPU, memória, conexões DB ou profundidade da fila (escolha o recurso que seu app costuma bater primeiro)

Se p95 está alto mas erros estão estáveis, abra um trace de uma rota lenta nos últimos 15 minutos. Um único trace frequentemente mostra se o tempo foi gasto no banco, em uma API externa ou esperando locks.

Então faça uma busca nos logs. Se você tem um relato de usuário específico, pesquise pelo request_id (ou pelo trace_id se você o guarda nos logs) e leia a timeline. Se não tiver, pesquise pela mensagem de erro mais comum na mesma janela de tempo e veja se bate com a lentidão.

Por fim, decida mitigar agora ou investigar mais. Se usuários estão bloqueados e a saturação está alta, uma mitigação rápida (scale up, rollback ou desativar uma feature não essencial) pode ganhar tempo. Se o impacto é pequeno e o sistema está estável, continue investigando com traces e logs de queries lentas.

Exemplo: diagnosticar um checkout lento sem adivinhar

Algumas horas após um release, tickets de suporte começam a chegar: “Checkout leva 20 a 30 segundos.” Ninguém reproduz no laptop, então começam as suposições. É aí que o kit inicial de observabilidade paga.

Primeiro, vá para as métricas e confirme o sintoma. O gráfico de p95 de latência para requisições HTTP mostra um pico claro, mas apenas para POST /checkout. Outras rotas parecem normais e a taxa de erro está estável. Isso estreita de “o site inteiro está lento” para “um endpoint ficou mais lento após o release”.

Em seguida, abra um trace para uma requisição lenta POST /checkout. A waterfall do trace deixa o culpado óbvio. Dois desfechos comuns:

• O span “PaymentProvider.charge” está levando 18 segundos, com a maior parte do tempo em espera.
• O span “DB: insert order” está lento, mostrando uma longa espera antes da query retornar.

Agora valide com logs, usando o mesmo request_id do trace (ou o trace_id se você o armazena nos logs). Nos logs dessa requisição, você vê warnings repetidos como “payment timeout reached” ou “context deadline exceeded”, além de retries adicionados no release novo. Se for o caminho do banco, os logs podem mostrar mensagens de espera por lock ou a query lenta registrada acima de um limite.

Com os três sinais alinhados, a correção fica direta:

• Fazer rollback para o release anterior para parar a dor.
• Adicionar um timeout explícito para a chamada ao pagamento (e limitar retries).
• Adicionar uma métrica da latência da dependência, por exemplo p95 da duração do payment provider e p95 da duração de queries no DB.

O importante é que você não ficou chutando. Métricas apontaram o endpoint, traces apontaram o passo lento e logs confirmaram o modo de falha com a requisição exata em mãos.

Erros comuns que fazem você perder tempo durante incidentes

A maior parte do tempo de incidente é desperdiçada em lacunas evitáveis: os dados estão lá, mas são ruidosos, arriscados ou falta o detalhe que conecta sintomas a causa. Um kit inicial de observabilidade só ajuda se permanecer utilizável sob estresse.

Uma armadilha comum é logar demais, especialmente bodies completos. Parece útil até você pagar por armazenamento enorme, buscas ficarem lentas e acabar capturando senhas, tokens ou dados pessoais. Prefira campos estruturados (route, status code, latency, request_id) e logue apenas pequenos trechos de input explicitamente permitidos.

Outro tempo perdido é ter métricas detalhadas mas impossíveis de agregar. Labels de alta cardinalidade como full user IDs, emails ou números de pedido podem explodir a contagem de séries métricas e tornar dashboards instáveis. Use labels mais grosseiras (nome da rota, método HTTP, classe de status, nome da dependência) e mantenha dados específicos do usuário nos logs, onde pertencem.

Erros que repetidamente bloqueiam diagnóstico rápido:

• Ficar olhando apenas médias. Médias escondem a dor real; cheque p95 e p99 quando usuários dizem “está lento”.
• Traces sem contexto. Se spans não têm nomes de rota e nomes claros de dependência, um trace vira uma imagem sem legendas.
• Sem marcador de release. Se não der pra ver quando uma versão mudou, você fica chutando se um deploy causou o problema.
• Alerts sem dono. Quando um alerta dispara e ninguém sabe o próximo passo, vira ruído e depois é ignorado.
• Logs não pesquisáveis. Logs em texto livre sem chaves consistentes transformam todo incidente num grep manual.

Um exemplo prático: se o p95 do checkout sobe de 800ms para 4s, você quer responder duas perguntas em minutos: começou logo após um deploy, e o tempo está no seu app ou em uma dependência (DB, payment provider, cache)? Com percentis, uma tag de release e traces com rota + nomes de dependências, você chega lá rápido. Sem isso, você queima a janela do incidente debatendo suposições.

Próximos passos: torne repetível para todo app novo

A vitória real é consistência. Um kit inicial de observabilidade só ajuda se cada novo serviço for lançado com o mesmo básico, nomeado do mesmo jeito e fácil de encontrar quando algo quebra.

Transforme suas escolhas do primeiro dia em um pequeno template que sua equipe reutilize. Mantenha pequeno, mas específico.

• Gere um request ID para cada requisição de entrada e carregue-o por logs e traces.
• Registre os poucos eventos que você sempre precisa: início/fim de requisição, erros (com tipo claro) e requisições lentas acima de um limite.
• Acompanhe um punhado de métricas principais: tráfego, taxa de erro, latência (p50 e p95) e um sinal de saturação (CPU, memória, pool do DB ou profundidade da fila).
• Adicione traces básicos para as rotas chave e as dependências principais (DB e uma API externa).
• Anexe labels de release/versão a logs, métricas e traces para poder responder: “isso começou após o deploy?”

Crie uma visão “home” que qualquer um possa abrir durante um incidente. Uma tela deve mostrar requests por minuto, taxa de erro, p95 de latência e sua métrica principal de saturação, com filtro por ambiente e versão.

Mantenha alertas mínimos no começo. Dois alerts já cobrem bastante: pico de taxa de erro em uma rota chave, e pico de p95 de latência na mesma rota. Se adicionar mais, garanta que cada um tenha uma ação clara.

Finalmente, estabeleça uma revisão mensal recorrente. Remova alerts ruidosos, aperfeiçoe nomes e adicione um sinal que teria economizado tempo no último incidente.

Para incorporar isso no seu processo de build, adicione um “gate de observabilidade” ao checklist de release: sem deploy sem request IDs, tags de versão, a visão home e os dois alerts base. Se você faz deploy com Koder.ai, pode definir esses sinais do primeiro dia no modo de planning antes do deploy, depois iterar com snapshots e rollback quando precisar ajustar rapidamente.