Boas Práticas de Observabilidade

Serviços Go em produção permanecem depuráveis quando logs, métricas, traces, probes e comportamento de shutdown seguem regras compartilhadas que protegem engenheiros de plantão e orçamentos de observabilidade.

Como Usar Esta Lista

• Adote as regras da Categoria A nos templates de serviço antes do primeiro deploy em produção.
• Codifique listas de permissão de rótulos e caminhos de probe em checklists de revisão de código.
• Emparelhe regras de métricas com dashboards Grafana e runbooks de alerta.
• Revise após crescimento significativo de tráfego ou novas dependências.

A - Logs e slog

• Emitir logs JSON em produção com um único manipulador padrão. Agregadores indexam campos de forma confiável; texto é apenas para desenvolvimento local.
• Incluir request_id e trace_id em cada linha de log com escopo de requisição. A equipe de plantão pode pular de uma linha de log para um trace sem ginástica de grep.
• Usar nomes de atributos estáveis entre serviços (err, http.route, user_id). Esquemas consistentes tornam consultas entre serviços possíveis.
• Definir o nível de log a partir do ambiente; padrão Info em produção. O volume de debug escala com QPS e aumenta o custo.
• Redigir segredos e tokens em um manipulador personalizado ou middleware. Senhas nunca devem chegar ao armazenamento de logs.
• Registrar erros uma vez na fronteira com contexto encapsulado. Evitar rastros de pilha duplicados em cada camada.

B - Métricas e cardinalidade

• Rotular métricas HTTP com templates de rota, não caminhos brutos. /users/{id} evita séries ilimitadas a partir de IDs.
• Nunca colocar IDs de usuário, e-mails ou IDs de pedido em rótulos do Prometheus. Explosões de cardinalidade derrubam backends de métricas.
• Registrar métricas uma vez em main, não por requisição. Registro duplicado causa pânico e duplica séries.
• Ajustar buckets de histograma para limites de SLO. Buckets padrão ocultam penhascos de latência perto do seu alvo p99.
• Expor /metrics em um listener de administração ou rede restrita. Scrape público vaza detalhes operacionais internos.
• Excluir tráfego de verificação de integridade dos gráficos RED ou rotular probe=true. QPS de probe distorce agregados de taxa e duração.

C - Tracing e amostragem

• Propagar context.Context através de handlers HTTP, gRPC e chamadas de banco de dados. Contexto quebrado quebra árvores de trace.
• Usar ParentBased ou amostragem de proporção em produção. Rastreamento completo em QPS alto sobrecarrega coletores.
• Registrar erros em spans com span.RecordError. Traces com falha devem permanecer visíveis sob amostragem.
• Chamar TracerProvider.Shutdown ao sair. Spans em buffer são descartados em SIGKILL sem flush.
• Definir service.name e atributos de recurso de ambiente de implantação. Backends agrupam traces por equipe e estágio.
• Span nas fronteiras de I/O, não em cada função auxiliar. Ruído oculta os spans que explicam a latência.

D - Saúde, prontidão e probes

• Manter liveness barata sem I/O externo. Verificações de dependência pertencem apenas à prontidão.
• Retornar 503 na prontidão quando dependências críticas falharem. Load balancers param o tráfego sem loops de reinicialização de pod.
• Permitir /healthz e /readyz no middleware de autenticação. Probes do Kubelet não enviam tokens bearer.
• Limitar probes de prontidão com timeouts de sub-segundo. Probes lentos causam flapping de endpoints durante interrupções parciais.
• Atrasar a prontidão até que as migrações e o aquecimento terminem. Tráfego antecipado causa erros de esquema e cache.
• Documentar startup vs prontidão vs liveness no README do serviço. Novos operadores devem saber qual endpoint significa o quê.

E - Shutdown e ciclo de vida

• Manipular SIGTERM e chamar http.Server.Shutdown com um contexto limitado. Deployments rolling drenam trabalho em andamento.
• Alinhar o timeout de shutdown com terminationGracePeriodSeconds do Kubernetes. Evitar SIGKILL no meio da requisição.
• Cancelar contextos de worker quando o drain HTTP começar. Pollers em segundo plano não devem sobreviver à janela de graça.
• Definir prontidão como falsa antes que o shutdown comece. Impede novo tráfego enquanto as requisições ativas terminam.
• Registrar fases de shutdown: sinal recebido, início do drain, concluído. Logs de deploy correlacionam-se com erros voltados para o usuário.
• Fechar pools de banco de dados e descarregar exportadores após o drain HTTP. Telemetria e conexões não devem vazar na saída.

F - Configuração e operabilidade

• Validar variáveis de ambiente necessárias na inicialização e sair com código diferente de zero em caso de falha. Configurações incorretas não devem se tornar um pod em execução.
• Registrar um snapshot seguro da configuração em Info na inicialização. Operadores verificam porta, ambiente e flags de recursos sem segredos.
• Injetar structs de configuração; não ler os.Getenv em handlers. Testes e clareza sofrem com acesso oculto ao ambiente.
• Tratar endpoints de observabilidade como parte do contrato público de operações. Documentar caminhos, portas e intervalos de scrape.
• Executar go test com manipuladores de teste slog para middleware crítico. Regressões no logging de requisições são capturadas em CI.
• Revisar a observabilidade em cada postmortem de incidente. Rótulos ou IDs ausentes se tornam um item de ação rastreado.

FAQs

Relacionados

• Production Go: Logs, Metrics, Traces, and Signals - visão geral conceitual
• Structured Logging with slog - detalhes de logging
• Prometheus Metrics & RED/USE Dashboards - métricas RED
• OpenTelemetry Tracing in Go Services - configuração de tracing
• Graceful Shutdown & Signal Handling - padrões de drain
• net/http Best Practices - regras complementares específicas de HTTP

Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verificar patch na compilação), chi (última versão - verificar na compilação), gin (última versão - verificar na compilação), echo (última versão - verificar na compilação), google.golang.org/grpc (última versão - verificar na compilação), sigs.k8s.io/controller-runtime (última versão - verificar na compilação), kubebuilder (última versão - verificar na compilação), tinygo (última versão - verificar alvos de placa na compilação), wazero (última versão - verificar na compilação) e golangci-lint (última versão - verificar conjunto de linters na compilação).