Observabilidade com Grafana

Aprenda, projete, construa e execute uma stack de observabilidade Grafana (métricas Prometheus, logs Loki, traces Tempo, coleta Alloy, dashboards e alertas Grafana) gerenciada como código com Terraform. Utilize quando for solicitado a aprender ou ensinar Grafana, PromQL ou LogQL; configurar monitoramento; escrever ou revisar um dashboard, uma regra de alerta, uma política de notificação, um ponto de contato, um pipeline Alloy ou Terraform para Grafana; ou depurar alertas barulhentos, silenciosos, travados em NoData ou que não alcançam ninguém.

O que é Observabilidade com Grafana?

Esta skill capacita o agente a atuar como um engenheiro de confiabilidade especializado em Grafana, permitindo projetar, construir e gerenciar uma stack de observabilidade de nível de produção. Ela cobre todo o ecossistema Grafana: métricas com Prometheus, logs com Loki, traces com Tempo e coleta de dados com Grafana Alloy, tudo orquestrado como código via Terraform. A skill é útil para aprender conceitos como PromQL e LogQL, criar e revisar dashboards e regras de alerta, configurar políticas de notificação e roteamento, e depurar problemas comuns como alertas ruidosos ou silenciosos. Ela impõe regras rígidas baseadas em incidentes reais, como sempre usar token de conta de serviço, nunca colocar notification_settings em uma regra, e verificar derivação (drift) antes de aplicar mudanças. O agente pode operar em três modos: aprendizado, construção ou planejamento de rollout, seguindo workflows e referências específicas para cada tarefa. A stack é gerenciada como código, com dashboards gerados por scripts e alertas definidos em Terraform, garantindo que a UI nunca seja a fonte da verdade. A skill também inclui um laboratório Docker Compose local e um stack Terraform inicial para começar rapidamente.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/louij2/grafana-observability-skill/tree/HEAD/.github/skills/grafana-observability

Installed? Explore more Produtividade e Colaboração skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. 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.
  2. 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.
  3. Proteja o plano salvo. Execute terraform plan -out, depois recuse qualquer delete/replace que você não pretendia, em qualquer recurso. Coloque prevent_destroy nas pastas. Excluir uma pasta do Grafana exclui todos os dashboards e regras dentro dela.
  4. 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.
  5. 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.
  6. 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.
  7. Roteie por acionabilidade e trate os intervalos de repetição como a alavanca real. Use severity (critical/warning/info) mais urgency=backlog para 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.
  8. Escalação deve ser um atraso, e um silêncio é o reconhecimento. A rota de página usa group_wait de 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 de keep_firing_for ≥ o tempo de espera, ou elas resolvem antes de escalar.
  9. 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.
  10. 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

  1. 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.
  2. 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?).
  3. 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.
  4. Verifique a derivação (drift), depois terraform plan -out=tfplan. Leia cada bloco ~ recolhido, especialmente em grafana_notification_policy, porque ele decide para onde todo alerta vai.
  5. Aplique o plano salvo com um token de conta de serviço. Use -target quando não tiver certeza.
  6. 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.
  7. 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

ArquivoAbra quando
learning-path.mdensinando ou aprendendo, estágio por estágio com laboratórios
architecture.mdescolhendo componentes, rótulos, retenção, autenticação, alta disponibilidade
queries.mdescrevendo PromQL ou LogQL, ou uma consulta parece errada
dashboards.mdconstruindo ou revisando um dashboard
alerting.mdregras, roteamento, pontos de contato, silêncios, fadiga
as-code.mdTerraform, API, backups, derivação, restaurações
meta-monitoring.mdprovando que o próprio monitoramento funciona
implementation-plan.mdintroduzindo 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.

Habilidades Relacionadas