Observabilidade e incidentes
Enxergar o sistema por dentro e reagir quando ele falha: logs, métricas, traces, SLOs, alertas úteis e relatos sem culpados.
Cerca de 16 min · Revisado em
Ao final, você vai conseguir
- Classificar informações como métricas, logs ou traces
- Escrever e analisar logs estruturados sem dados pessoais
- Calcular SLI e orçamento de erros a partir de um SLO
- Distinguir um alerta de sintoma acionável de um alerta de ruído
- Conduzir um incidente da detecção ao relato pós-incidente sem culpados
Dia 5, dia de pagamento, e as pessoas reclamam nas redes que o app não fecha o pedido. Você tem duas opções: abrir o código e adivinhar, ou abrir um painel e ver em um minuto que só o pagamento falha, desde as 9h12, por causa de um banco sem resposta. Observabilidade é o que permite a segunda opção. Saber operar um sistema quando ele falha é o que faz alguém confiar em você para colocá-lo no ar.
Três jeitos de enxergar um sistema
- Métricas
- Números medidos ao longo do tempo: requisições por segundo, porcentagem de erros, uso de memória. Baratas de guardar, ótimas para gráficos e alertas. Respondem “quanto e quando”.
- Logs
- Registros de eventos, linha a linha, com horário: “pedido 812 recusado: cartão expirado”. Respondem “o que aconteceu exatamente”.
- Traces
- O caminho de uma requisição por todos os serviços, com o tempo gasto em cada etapa (cada etapa é um span). Respondem “onde está a demora ou o erro”.
Observabilidade é a capacidade de entender o que acontece dentro de um sistema olhando para o que ele emite de fora. O OpenTelemetry é o padrão aberto mais usado para gerar esses três sinais, independentemente da ferramenta que vai exibi-los.
Que tipo de sinal é cada informação?
Métrica · Log · Trace
- Gráfico de requisições por minuto na última hora
ERROR pagamento recusado pedido=812 motivo=timeout- Uma requisição levou 3 s: 2,8 s foram esperando o serviço de pagamento
- Uso de memória do banco: 87%
INFO usuario 45 fez login- O caminho de um pedido: app, API, estoque, pagamento
Logs que uma máquina consegue ler
Um log em texto livre, como Erro ao pagar o pedido 812!!, é fácil de escrever e difícil de pesquisar. Um log estruturado guarda cada informação num campo com nome, normalmente em JSON. Aí dá para perguntar “quantos erros por rota na última hora?” em vez de ler linha por linha.
Uma linha de log estruturado em JSON.
{ "hora": "2026-10-05T09:12:44.318Z", "nivel": "error", "servico": "api-pedidos", "msg": "pagamento recusado", "pedido_id": 812, "rota": "/pagamento", "status": 502, "ms": 3004, "trace_id": "4bf92f3577b34da6" }- Horário: Em formato padrão e em UTC (horário universal). Com servidores em lugares diferentes, é a única forma de pôr os eventos em ordem.
- Nível: A gravidade:
debug,info,warn,error. Em produção, costuma-se guardar a partir deinfo. Reserveerrorpara o que precisa de atenção. - Serviço: Quem escreveu o log. Com vários serviços mandando logs para o mesmo lugar, é o primeiro filtro que você vai usar.
- Mensagem: Uma frase curta e fixa. Os detalhes que variam vão em campos próprios, para a mensagem poder ser agrupada.
- Contexto: Os dados que permitem investigar: qual pedido, qual rota, qual resposta, quanto tempo. Números ficam como números, para dar para somar e comparar.
- trace_id: O código do trace dessa requisição. Com ele, você pula do log para o caminho completo do pedido e vê os logs dos outros serviços na mesma requisição.
Contando erros a partir dos logs
Cada linha é um log em JSON. Conte quantas requisições tiveram erro de servidor (status 500 ou mais), calcule a taxa de erro (erros dividido pelo total) e preencha erros_por_rota com quantos erros cada rota teve.
import json
linhas = [
'{"nivel": "info", "rota": "/pedidos", "status": 200, "ms": 120}',
'{"nivel": "info", "rota": "/pedidos", "status": 201, "ms": 180}',
'{"nivel": "error", "rota": "/pagamento", "status": 502, "ms": 3000}',
'{"nivel": "info", "rota": "/cardapio", "status": 200, "ms": 45}',
'{"nivel": "error", "rota": "/pagamento", "status": 504, "ms": 5000}',
'{"nivel": "warn", "rota": "/pedidos", "status": 404, "ms": 30}',
'{"nivel": "info", "rota": "/cardapio", "status": 200, "ms": 50}',
'{"nivel": "error", "rota": "/pagamento", "status": 500, "ms": 900}',
]
erros = 0
erros_por_rota = {}
for linha in linhas:
evento = json.loads(linha)
# se evento["status"] for 500 ou mais:
# some 1 em erros e 1 na rota do evento
pass
taxa = 0
print(f"Erros 5xx: {erros} de {len(linhas)} ({taxa:.1%})")
print("Por rota:", erros_por_rota)
- Conta só os erros de servidor (o 404 não entra)
- A taxa de erro é erros dividido pelo total de linhas
- Os erros estão agrupados por rota
Os quatro sinais que importam
Dá para medir milhares de coisas. O livro de SRE do Google propõe começar por quatro, os sinais de ouro, porque descrevem o que a pessoa usuária sente.
Latência
Quanto demora
O tempo para responder. Meça separado para sucessos e erros: um erro rápido pode puxar a média para baixo e esconder o problema.
Tráfego
Quanto pedem
Requisições por segundo, pedidos por minuto. Uma queda brusca de tráfego também é sinal de problema: talvez ninguém consiga chegar.
Erros
Quanto falha
A fração de requisições que falham, como respostas 5xx ou pedidos que não foram concluídos.
Saturação
Quão cheio está
O quanto do recurso mais escasso está em uso: memória, conexões com o banco, fila. Avisa antes de transbordar.
Para latência, a média engana. Use percentis: o p95 é o tempo abaixo do qual estão 95% das requisições. Se o p95 é 2 s, 1 em cada 20 pessoas esperou 2 s ou mais.
O painel mostra latência média de 180 ms, mas o p99 está em 6 segundos. Como você interpreta?
- A maioria é rápida, mas 1% das requisições está muito lenta e merece investigação
- Está tudo bem, porque a média é baixa
- O painel está errado, porque a média e o p99 deveriam ser parecidos
O trace de um pedido lento: onde foram os 3 segundos?
- App → API: POST /pedidos. O trace começa aqui, com um
trace_idque vai viajar junto com a requisição por todos os serviços. - API → Banco: Salva pedido · 12 ms. Um span rápido. O banco não é o problema.
- API → Pagamentos: Cobrar · 2.840 ms. O span que domina o tempo total. O serviço de pagamento está demorando quase 3 segundos para responder.
- Pagamentos → API: Aprovado. A resposta chega, mas tarde. Sem trace, a API pareceria a culpada.
- API → App: 201 em 2,9 s. A pessoa recebe a confirmação, depois de quase 3 segundos olhando um carregando.
Quanto de falha é aceitável
Nenhum sistema acerta 100% das vezes, e tentar custa caro demais. Então o time combina uma meta. Três siglas organizam essa conversa.
- SLI (indicador)
- O que você mede, do ponto de vista de quem usa. Exemplo: a fração de requisições ao checkout respondidas com sucesso em menos de 1 s.
- SLO (objetivo)
- A meta para o SLI num período. Exemplo: 99,9% das requisições boas em 30 dias.
- Orçamento de erros
- O quanto pode falhar sem quebrar o SLO: 100% menos a meta. Com 99,9%, sobra 0,1% para falhas, lançamentos arriscados e imprevistos.
| SLO | Orçamento | Indisponibilidade permitida |
|---|---|---|
| 99% | 1% | cerca de 7 horas e 12 minutos |
| 99,9% | 0,1% | cerca de 43 minutos |
| 99,99% | 0,01% | cerca de 4 minutos |
O orçamento vira uma regra de decisão: se ainda sobra, o time pode lançar coisas novas com mais liberdade; se acabou, a prioridade passa a ser confiabilidade.
Calculando o orçamento de erros do mês
O checkout recebeu 1.200.000 requisições no mês e 1.500 falharam. A meta é 99,9%. Calcule o sli, o orcamento (quantas falhas a meta permite), o gasto (que porcentagem do orçamento já foi usada) e diga em dentro_do_slo se a meta foi cumprida.
total = 1_200_000
falhas = 1_500
slo = 0.999
sli = 0 # fração de requisições boas
orcamento = 0 # total x (1 - slo)
gasto = 0 # falhas / orcamento x 100
dentro_do_slo = True
print(f"SLI: {sli:.3%}")
print(f"Orçamento: {orcamento:.0f} falhas | gasto: {gasto:.0f}%")
print("Dentro do SLO?", dentro_do_slo)
- O SLI é a fração de requisições boas
- O orçamento permite 1.200 falhas no mês
- O gasto mostra que o orçamento estourou (125%)
- A meta não foi cumprida
O resultado mostra 99,875% de sucesso. Parece ótimo. Por que o time deveria se preocupar?
Porque a meta combinada era 99,9%, e o orçamento foi gasto em 125%. Em números absolutos, 300 falhas além do aceitável. Pela regra do orçamento, é hora de pausar lançamentos arriscados e investir em confiabilidade até a situação voltar.
Alertas que valem acordar alguém
Um alerta é uma regra que chama uma pessoa quando uma métrica passa de um limite. Alerta demais é tão ruim quanto nenhum: quem recebe dez falsos por noite começa a ignorar, e ignora também o verdadeiro.
A regra prática é alertar pelo sintoma (o que a pessoa usuária sente: erros, lentidão) e não pela causa (CPU alta, um container reiniciado). CPU em 90% sem ninguém afetado não é emergência. E todo alerta deve ser acionável: quem recebe precisa saber o que fazer.
Este alerta deveria chamar alguém de madrugada?
Bom alerta: sintoma e acionável · Ruído: melhor virar painel ou aviso de dia
- Taxa de erro do checkout acima de 2% por 5 minutos
- CPU de um servidor passou de 80% por 1 minuto
- Orçamento de erros sendo gasto 10 vezes mais rápido que o normal
- Apareceu uma linha de log com nível
warn - p95 da busca acima de 2 s por 10 minutos
- Um container reiniciou uma vez, sem erros para as pessoas usuárias
Quando dá errado de verdade
Um incidente é qualquer situação que afeta as pessoas usuárias e precisa de resposta agora. A prioridade é mitigar (fazer o serviço voltar), não descobrir a causa profunda. Investigação completa vem depois, com calma.
Diagnosticando uma API fora do ar
O alerta disparou: a API da loja responde erro. Ela roda com Docker Compose num servidor. Investigue e restaure o serviço.
Consulte o health check da API e veja o status da resposta.
curl -i http://localhost:8000/healthHTTP/1.1 503 Service Unavailable content-type: application/json {"status":"erro","banco":"indisponivel"}Veja o estado dos containers do projeto.
docker compose psNAME IMAGE SERVICE STATUS loja-api-1 loja:1.4.0 api Up 3 hours loja-db-1 postgres:16 db Exited (137) 12 minutes agoLeia as últimas 20 linhas de log da API para confirmar o que ela vê.
docker compose logs api --tail 20api-1 | {"nivel":"error","msg":"falha ao conectar no banco","host":"db:5432","erro":"connection refused"} api-1 | {"nivel":"error","msg":"falha ao conectar no banco","host":"db:5432","erro":"connection refused"}Mitigue: suba de novo o serviço do banco em segundo plano.
docker compose up -d db[+] Running 1/1 ✔ Container loja-db-1 StartedConfirme que a API voltou a responder.
curl -i http://localhost:8000/healthHTTP/1.1 200 OK content-type: application/json {"status":"ok","banco":"ok"}
O serviço voltou. O incidente acabou? O que o código Exited (137) sugere para a investigação?
O impacto acabou, a investigação não. O código 137 indica que o processo foi encerrado à força, muitas vezes por falta de memória. Se ninguém investigar, vai acontecer de novo. Esse é o assunto do relato pós-incidente.
Coloque em ordem as etapas de resposta a um incidente.
- Um alerta de sintoma dispara
- Alguém assume a coordenação e declara o incidente
- O time avisa as pessoas afetadas sobre o problema
- O serviço é restaurado, com rollback ou outra mitigação
- As métricas confirmam que a situação normalizou
- O time escreve o relato pós-incidente sem culpados
- As ações de melhoria entram no planejamento
Um runbook é o roteiro escrito para um alerta: o que olhar primeiro, quais comandos rodar, quando escalar. Ele transforma o conhecimento de uma pessoa experiente em algo que alguém nova no time consegue seguir às 3h da manhã. Inclua também como restaurar um backup, e teste a restauração: backup nunca restaurado é só uma esperança.
O relato pós-incidente (*postmortem*) conta o que aconteceu, a linha do tempo, o impacto, as causas e as ações para não repetir. Ele é sem culpados: parte do princípio de que as pessoas agiram da melhor forma com o que sabiam, e procura o que no sistema permitiu o erro.
No relato de um incidente, qual destas frases segue a cultura sem culpados?
- O comando de limpeza apagou a tabela porque o script não pedia confirmação em produção
- O Lucas foi descuidado e rodou o comando errado
- Foi falta de atenção, e o time vai prestar mais atenção
Fechamento
- Métricas dizem quanto e quando, logs dizem o que aconteceu, traces dizem onde; juntos, explicam o sistema por fora.
- Logs estruturados em JSON, com contexto e sem dados pessoais, podem ser pesquisados e contados.
- Latência, tráfego, erros e saturação são os sinais de ouro; para latência, use percentis em vez de média.
- O SLI mede, o SLO é a meta e o orçamento de erros é a margem que orienta quando lançar e quando estabilizar.
- Alerte por sintomas acionáveis, mitigue primeiro, siga runbooks e escreva relatos sem culpados.
Derrube, recupere e conte a história
Use uma aplicação sua com API e banco rodando em Docker Compose. Você vai provocar uma falha de propósito, recuperar o serviço e escrever o relato como um time de verdade faria.
- Adicione logs estruturados em JSON e um endereço
/healthque verifica o banco - Defina um SLI e um SLO para a rota principal e escreva qual seria o alerta de sintoma
- Pare o container do banco e observe o que o health check e os logs mostram
- Recupere o serviço seguindo um runbook curto que você escreveu antes
- Faça um backup do banco, apague os dados de teste e restaure a partir do backup
- Escreva um relato pós-incidente sem culpados com linha do tempo, impacto, causa e duas ações