O que Observabilidade com Grafana faz?
Estas são as práticas de uma stack auto-hospedada de nível de produção: cerca de 60 dashboards, mais de 400 regras de alerta, 50 jobs de scraping, logs e traces, tudo gerenciado como código. Cada regra abaixo existe porque quebrá-la causou um incidente real. O porquê é fornecido para que você possa julgar casos de borda.
Escolha primeiro o modo
- Aprendizagem ("me ensine", "explique", "o que é", "me teste"): siga references/learning-path.md. Ensine um estágio por vez e execute o laboratório em assets/lab/. Verifique a compreensão antes de prosseguir. Não despeje todos os estágios de uma vez.
- Construção (um dashboard, alerta, pipeline, Terraform ou rollout): siga o fluxo de trabalho abaixo e abra apenas o arquivo de referência que a tarefa necessita.
- Planejando um rollout em uma organização: references/implementation-plan.md.
A stack em uma imagem
apps / hosts / network kit / cloud APIs
│ metrics (exporters, /metrics) │ logs (files, docker, syslog) │ traces (OTLP)
▼ ▼ ▼
Prometheus ◄── scrape ── Grafana Alloy (collector: discover, relabel, redact, ship)
│ │ │
│ Loki Tempo
└──────────────┬────────────────────┴────────────────────────────────┘
▼
Grafana ── dashboards, Explore, alerting ──► contact points (chat, email, on-call)
▲
Terraform (folders, data sources, rules, routing) + scripts (dashboards) + git
Detalhes: references/architecture.md.
As regras rígidas
- Código é a fonte da verdade. Altere a configuração de alertas através do Terraform e construa dashboards com um script gerador ou JSON que resida no git. Um clique na UI se perde na próxima aplicação, ou pior, a próxima aplicação o reverte silenciosamente.
- Antes de qualquer apply, verifique ambos os tipos de derivação (drift). (a) Regras que existem ao vivo mas não no código: um apply sem alvo específico as exclui. (b) Regras que estão no código mas foram alteradas ao vivo: um apply as reverte. Um plano "Sem alterações" não prova nada sobre regras que o Terraform nunca viu. Veja references/as-code.md.
- Proteja o plano salvo. Execute
terraform plan -out, depois recuse qualquerdelete/replaceque você não pretendia, em qualquer recurso. Coloqueprevent_destroynas pastas. Excluir uma pasta do Grafana exclui todos os dashboards e regras dentro dela. - Use um token de conta de serviço, nunca
admin:password. Se o estado foi criado com autenticação por token, um apply com autenticação básica planeja excluir e recriar pastas, pontos de contato e a árvore de políticas. Isso já limpou 59 dashboards e toda a árvore de roteamento em um único apply. - Nunca coloque
notification_settings(ponto de contato) em uma regra. Uma regra que tem um ponto de contato pula completamente a árvore de políticas. Ela escapa do roteamento por severidade, intervalos de repetição e temporizações de silêncio. Em um ambiente, 196 de 217 regras faziam isso e ninguém percebeu. - Coloque o limite no estágio de limite do Grafana, não dentro do PromQL. Com
expr > 90, um host saudável não retorna séries, o que o Grafana interpreta como NoData, não OK. Consulte o valor bruto; compare-o no estágio C. - Roteie por acionabilidade e trate os intervalos de repetição como a alavanca real. Use
severity(critical/warning/info) maisurgency=backlogpara problemas crônicos e conhecidos. A maior parte do ruído de alerta é re-notificação de algo já conhecido. Repita alertas críticos diariamente e avisos semanalmente, não a cada hora. - Escalação deve ser um atraso, e um silêncio é o reconhecimento. A rota de página usa
group_waitde cerca de 15 minutos, então ela dispara apenas se o alerta ainda estiver em estado de disparo e não silenciado. Regras do tipo evento precisam dekeep_firing_for≥ o tempo de espera, ou elas resolvem antes de escalar. - Monitore o monitoramento. Fique de olho em falhas de avaliação, falhas na entrega de notificações, alertas suprimidos (silenciados), exporters obsoletos e backups que pararam. Um sistema de alerta silencioso parece exatamente igual a um saudável. Veja references/meta-monitoring.md.
- Verifique, não confie. Execute cada painel ou consulta de alerta contra a fonte de dados antes de escrevê-la. Após qualquer escrita via API, leia o objeto de volta e afirme que sua mudança está nele: a resposta POST não informa qual conteúdo foi enviado. O acordo entre duas pessoas ou duas sessões não é verificação; um comando é.
Fluxo de trabalho para qualquer mudança
- Declare a pergunta que o painel ou alerta responde, e quem age sobre ela. Se ninguém agisse sobre um alerta, é um painel de dashboard, não um alerta.
- Comprove a consulta no Explore ou através da API de proxy da fonte de dados. Verifique se ela retorna dados, se os rótulos são aqueles pelos quais você vai agrupar ou rotear, e como ela se comporta quando saudável (vazia? zero?).
- Escreva em código: um grupo de regras Terraform, um gerador de dashboard ou uma configuração Alloy. Siga references/alerting.md ou references/dashboards.md.
- Verifique a derivação (drift), depois
terraform plan -out=tfplan. Leia cada bloco~recolhido, especialmente emgrafana_notification_policy, porque ele decide para onde todo alerta vai. - Aplique o plano salvo com um token de conta de serviço. Use
-targetquando não tiver certeza. - Leia de volta da API, confirme que a regra está avaliando (estado não é Error/NoData) e, para alertas, dispare um teste de ponta a ponta para o ponto de contato real.
- Faça commit com o porquê. Deixe um comentário no código sempre que uma escolha parecer errada, mas for intencional.
Definição de pronto
Regra de alerta: no Terraform; rótulo severity definido; modelos de resumo e descrição incluem o host ou serviço afetado e o valor atual; no_data_state escolhido de propósito; for longo o suficiente para não oscilar; roteado pela árvore (sem ponto de contato por regra); um link para runbook ou um primeiro passo na descrição; testado de ponta a ponta; não gera duplicação de página com uma regra existente.
Dashboard: no git (gerado, ou exportado com id/versão removidos); na pasta correta; vinculado ao hub de visão geral e vice-versa; variáveis para ambiente/host; cada painel tem um título que pergunta ou responde a uma pergunta; unidades e limites definidos; keepTime em links.
Novo exporter ou fonte de dados: scrapy com rótulos estáveis (env, team, service, role); coberto pela regra de frota up == 0 (não adicione uma separada); se tiver uma métrica de última execução ou frescor, uma regra de obsolescência; adicionado à auditoria de meta-monitoramento; a fonte de dados tem um uid fixo.
Índice de referências
| Arquivo | Abra quando |
|---|---|
| learning-path.md | ensinando ou aprendendo, estágio por estágio com laboratórios |
| architecture.md | escolhendo componentes, rótulos, retenção, autenticação, alta disponibilidade |
| queries.md | escrevendo PromQL ou LogQL, ou uma consulta parece errada |
| dashboards.md | construindo ou revisando um dashboard |
| alerting.md | regras, roteamento, pontos de contato, silêncios, fadiga |
| as-code.md | Terraform, API, backups, derivação, restaurações |
| meta-monitoring.md | provando que o próprio monitoramento funciona |
| implementation-plan.md | introduzindo Grafana para uma equipe ou empresa |
Ativos: assets/lab/ é um laboratório Docker Compose local. assets/terraform-starter/ é um stack Terraform inicial com as defaults seguras já conectadas.