Dashboards e Grafana

Um dashboard é uma hipótese sobre o que importa monitorar. Dashboards criados sem critério acumulam panels que sempre estão "verdes", não respondem perguntas reais durante incidentes, e criam uma falsa sensação de visibilidade. A diferença entre um dashboard útil e um de vaidade está na pergunta que guia cada panel: "se este panel estiver vermelho, sei exatamente o que fazer?" — se a resposta for não, o panel não deveria existir ou precisar ser reformulado.

Os 4 Golden Signals

O Google SRE Book define quatro sinais que, juntos, capturam o estado de saúde de qualquer serviço orientado a requests. Um dashboard bem construído começa com eles — qualquer dashboard que não responda a esses quatro sinais está incompleto para uso operacional.

1. Latência

O tempo que leva para servir um request. Crucial: distinguir a latência de requests com sucesso da latência de requests com erro. Um erro que retorna em 1ms e um sucesso que demora 800ms são comportamentos completamente diferentes — misturá-los distorce o percentil puxando-o artificialmente para baixo. Prefira histogramas a médias: a média de latência esconde a long tail. P50, P95, P99 revelam a experiência dos diferentes percentis de usuários. Um P50 de 50ms com P99 de 5s indica que 1% dos usuários tem uma experiência péssima que a média mascara completamente.

2. Traffic (Tráfego)

A demanda sendo colocada sobre o sistema. Para serviços HTTP: requests por segundo. Para bancos de dados: queries por segundo. Para streaming: mensagens por segundo ou bytes/s. O tráfego é o denominador que dá contexto a erros e latência — 10 erros em 100 req/s (10%) é um incidente grave; 10 erros em 10.000 req/s (0.1%) pode estar dentro do SLO.

3. Errors (Erros)

A taxa de requests que falham. Inclui falhas explícitas (5xx), implícitas (200 com payload inválido ou truncado), e por política (requests que violam SLO de latência — um 200 em 10 segundos pode ser considerado falha funcional). O error rate deve ser visualizado como fração do tráfego total, não como contagem absoluta, para ter sentido independente do volume.

4. Saturation (Saturação)

Quão "cheio" está o serviço — a fração da capacidade total sendo utilizada. CPU, memória, I/O de disco, pool de conexões, tamanho de fila de mensagens. A saturação é preditiva: um serviço em 80% de CPU provavelmente vai degradar antes de chegar a 100%. Acompanhe a tendência (rate of change) além do valor instantâneo — crescimento linear de uso de memória aponta para um memory leak antes que cause OOM.

Estrutura de um Dashboard Eficaz

Um dashboard mal estruturado é tão prejudicial quanto nenhum dashboard — causa confusão durante incidentes e dificulta a leitura de tendências. O princípio fundamental: organize do macro para o micro.

Hierarquia top-down

Visão de saúde geral no topo (SLO status, error budget), depois golden signals por serviço, depois detalhes (por endpoint, por instância, por região). Durante um incidente, você lê de cima para baixo — a primeira linha deve responder "está tudo bem?" em 5 segundos. Detalhes de diagnóstico ficam em rows colapsáveis ou dashboards separados.

Consistência de time range

Todos os panels do mesmo dashboard devem usar o mesmo time range via variável $__timeRange. Mixar panels com ranges fixos diferentes cria comparações enganosas — um spike parece diferente dependendo do zoom. Evite hardcodar ranges em panels individuais; use sempre o time range global do dashboard.

Thresholds visuais nos panels

Grafana suporta thresholds visuais: linha vermelha ou fundo colorido ao cruzar um valor. Use isso para mostrar o SLO target diretamente no gráfico — o engenheiro vê imediatamente quando a métrica está abaixo do objetivo sem precisar lembrar o número de cabeça.

Data links para correlação

Configure data links: clicar em um spike de error rate deve abrir o trace correspondente no Jaeger/Tempo, ou os logs correlacionados no Loki. Essa navegação entre sinais é o que diferencia um stack de observabilidade integrado de ferramentas desconectadas.

// Data link no Grafana — de métrica para trace (Tempo)
{
  "title": "View traces",
  "url": "/explore?left=${__data.fields.traceID}&datasource=Tempo",
  "targetBlank": true
}

// Data link de métrica para logs (Loki) — com correlação por label
{
  "title": "View logs for ${__series.name}",
  "url": "/explore?left={\"datasource\":\"Loki\",\"queries\":[{\"expr\":\"{service=\\\"${__series.name}\\\"}|=\\\"error\\\"\"}]}&from=${__value.time}&to=${__value.time}+300000",
  "targetBlank": true
}

Variáveis de Template

Variáveis de template tornam dashboards reutilizáveis através de serviços, ambientes e instâncias — eliminam a necessidade de duplicar dashboards para cada variação. Um único dashboard parametrizado por $environment e $service serve toda a plataforma.

// Variável: ambiente (query em labels do Prometheus)
name: environment
type: query
query: label_values(http_requests_total, environment)
// resultado: [production, staging, development]

// Variável: serviço (dependente do ambiente selecionado)
name: service
type: query
query: label_values(http_requests_total{environment="$environment"}, service)

// Variável: instância (dependente do serviço selecionado)
name: instance
type: query
query: label_values(up{service="$service"}, instance)

// Variável de intervalo — adapta a resolução ao zoom do time range
name: interval
type: interval
values: [1m, 5m, 10m, 30m, 1h]
auto: true  // Grafana escolhe baseado no time range ativo

// Uso nos panels:
// rate(http_requests_total{
//   environment="$environment",
//   service="$service"
// }[$interval])

Dashboard as Code

Dashboards criados manualmente na UI têm os mesmos problemas que infraestrutura sem IaC: impossível revisar mudanças em PR, difícil replicar entre ambientes, sem histórico de alterações, e sem forma de garantir consistência entre dashboards de serviços diferentes. Dashboard as code resolve isso tratando dashboards como artefatos de software.

Abordagens

• Grafana JSON + Git: exportar o JSON do dashboard e versionar. Simples, sem dependências, mas JSON de dashboard tem centenas ou milhares de linhas — difícil de criar e editar programaticamente, e diffs são ilegíveis.
• Grafonnet: biblioteca Jsonnet para criar dashboards programaticamente. Expressiva, permite abstrações (funções que geram panels padrão de golden signals para qualquer serviço), mas requer aprender Jsonnet.
• Terraform provider grafana: gerenciar dashboards, datasources, alertas e pastas como recursos Terraform. Boa opção se o time já usa Terraform para infra — o mesmo workflow de plan/apply/review.
• grafanalib (Python): gerar JSON de dashboards via Python. Mais familiar para times Python mas com menos abstrações que Grafonnet.

// Terraform — dashboard e alerta de SLO como código
resource "grafana_dashboard" "service_overview" {
  config_json = templatefile("${path.module}/dashboards/service-overview.json", {
    datasource = var.prometheus_datasource_uid
    service    = var.service_name
  })
  folder = grafana_folder.team_platform.id
}

resource "grafana_rule_group" "slo_alerts" {
  name             = "${var.service_name}-slo"
  folder_uid       = grafana_folder.team_platform.uid
  interval_seconds = 60

  rule {
    name      = "HighErrorBurnRate"
    condition = "C"

    data {
      ref_id         = "A"
      datasource_uid = var.prometheus_datasource_uid
      model = jsonencode({
        expr = "rate(http_requests_total{status=~'5..', service='${var.service_name}'}[1h]) / rate(http_requests_total{service='${var.service_name}'}[1h])"
      })
    }

    data {
      ref_id         = "C"
      datasource_uid = "__expr__"
      model = jsonencode({
        type       = "threshold"
        conditions = [{ evaluator = { type = "gt", params = [0.01] } }]
      })
    }

    annotations = {
      summary     = "${var.service_name}: high error rate"
      runbook_url = "https://wiki.internal/runbooks/${var.service_name}"
    }
    labels = {
      severity = "page"
      team     = var.team
    }
  }
}

SLO Dashboard

Um dashboard de SLO é separado dos dashboards operacionais — seu propósito é responder perguntas de negócio: "quanto do error budget resta? estamos consumindo budget em ritmo sustentável? quando o budget vai esgotar se mantiver o ritmo atual?"

// PromQL — panels essenciais de um SLO dashboard

// Panel 1: Success Rate atual (stat/gauge)
sum(rate(http_requests_total{status!~"5.."}[5m]))
/ sum(rate(http_requests_total[5m]))
// threshold: red < 0.998, yellow < 0.999, green >= 0.999

// Panel 2: Error Budget Restante (gauge em %)
1 - (
  (1 - avg_over_time(
    (
      sum(rate(http_requests_total{status!~"5.."}[5m]))
      / sum(rate(http_requests_total[5m]))
    )[30d:5m]
  ))
  / (1 - 0.999)  // dividido pelo budget total (0.001)
)
// threshold: red < 0, yellow < 0.25, green >= 0.25

// Panel 3: Burn Rate 1h (stat)
(1 - sum(rate(http_requests_total{status!~"5.."}[1h])) / sum(rate(http_requests_total[1h])))
/ (1 - 0.999)
// threshold: red > 14.4, yellow > 6, green <= 6

// Panel 4: Série histórica 30d com SLO target (timeseries)
avg_over_time(
  (
    sum(rate(http_requests_total{status!~"5.."}[5m]))
    / sum(rate(http_requests_total[5m]))
  )[30d:1h]
)
// Adicionar constant threshold line em 0.999 — área abaixo é erro acumulado visível

// Panel 5: Budget consumido por dia (bar chart)
// Minutos de budget consumidos em cada dia
(1 - day:success_rate:avg) * 24 * 60

Correlação de Sinais no Grafana

O valor máximo do Grafana aparece quando você conecta métricas, logs e traces em um único workflow de investigação. Sem correlação, você navega manualmente entre ferramentas copiando timestamps e IDs — com correlação, a navegação é um clique.

Métricas → Traces via Exemplars

Quando o Prometheus scrape inclui exemplars em histogramas (OTel os emite automaticamente), o Grafana exibe diamantes no gráfico de série temporal. Clicar em um diamante abre o trace correspondente no Tempo — você vai diretamente do spike do P99 para o trace que causou aquele spike.

Logs → Traces via Trace ID

Se os logs contêm o trace_id (injetado via OTel Logs Bridge), o Loki Explore detecta automaticamente o campo e exibe um botão "View Trace" — abre o trace no Tempo sem busca manual. Configure "derived fields" no datasource Loki para ativar essa detecção.

Traces → Logs via Trace ID

No Tempo, o Grafana mostra logs do Loki correlacionados ao trace — todos os logs emitidos durante o span são exibidos ao lado do trace waterfall. Requer configuração de "trace to logs" no datasource Tempo.

// Grafana datasource Tempo — configuração de correlação bidirecional
{
  "tracesToLogsV2": {
    "datasourceUid": "loki-uid",
    "spanStartTimeShift": "-1m",
    "spanEndTimeShift": "1m",
    "tags": ["service.name", "host.name"],
    "filterByTraceID": true,
    "filterBySpanID": false,
    "customQuery": true,
    "query": "{service=\"${__tags.service.name}\"} |= \"${__trace.traceId}\""
  },
  "tracesToMetrics": {
    "datasourceUid": "prometheus-uid",
    "queries": [
      {
        "name": "Request rate",
        "query": "rate(http_requests_total{service=\"$${__tags.service.name}\"}[5m])"
      },
      {
        "name": "Error rate",
        "query": "rate(http_requests_total{service=\"$${__tags.service.name}\",status=~\"5..\"}[5m])"
      }
    ]
  }
}

Anti-patterns de Dashboard

• Dashboard de vaidade: cheio de métricas de uptime que sempre estão "verdes". Não responde à pergunta "tem algum problema?". Todo panel deve ter uma condição concreta em que ficaria vermelho.
• Médias sem percentis: latência média de 100ms não diz nada sobre o P99. Apresente sempre P50/P95/P99 — nunca só a média para métricas de latência.
• Escala Y fixada muito alta: um gráfico com eixo Y de 0-100% onde a métrica fica sempre entre 98-99.9% não mostra variação relevante. Fixe o mínimo perto do valor real (ex: 97%) para amplificar as variações que importam.
• Muitos panels sem hierarquia: 30 panels exibidos de uma vez sobrecarregam cognitivamente durante incidentes. Use rows colapsáveis para esconder detalhes de diagnóstico — visíveis apenas quando necessário.
• Dashboard sem owner: dashboards sem responsável ficam desatualizados. Todo dashboard deve ter um label de team. O Grafana exibe "last viewed" e "last updated" — use esses dados para identificar dashboards obsoletos em revisões semestrais.
• Service names hardcoded: um dashboard hardcoded para um serviço específico não escala. Use variáveis de template — um único dashboard parametrizado serve toda a plataforma.

Como praticar

1. Crie um dashboard de golden signals parametrizado com variáveis de template para $environment e $service: um panel de error rate (fração de 5xx sobre total), um panel de latência (P50/P95/P99 via histograma), um panel de tráfego (req/s), e um panel de saturation (CPU ou pool de conexões). Adicione thresholds visuais no panel de error rate com o SLO target.
   Critério: trocar $environment de production para staging exibe as métricas corretas sem editar nenhuma query; o panel de latência mostra três linhas (P50/P95/P99) e não a média; o panel de error rate tem threshold visual vermelho acima do SLO; o dashboard funciona para pelo menos 2 serviços diferentes sem duplicação.
2. Configure correlação completa de sinais em um stack local (Docker Compose com Prometheus, Grafana, Tempo, Loki, OTel Collector): habilite exemplars no histograma de latência, configure o datasource Prometheus no Grafana para exibir exemplars com link para Tempo, e configure trace to logs no datasource Tempo. Gere requests e valide a navegação completa: spike na métrica → clique no diamante → trace no Tempo → logs do trace no Loki.
   Critério: diamantes (exemplars) aparecem no gráfico de latência P99; clicar em um diamante abre o trace correspondente no Tempo; dentro do trace, o botão "Logs for this span" exibe logs do Loki com o mesmo trace_id; a navegação completa funciona em menos de 3 cliques.
3. Implemente um SLO dashboard completo para um serviço: success rate atual (stat), error budget restante em % (gauge com threshold em 25%), burn rate da última 1h (stat com threshold em 14.4×), e série histórica de 30 dias com linha de referência do SLO target. Valide que os panels mostram os valores corretos simulando diferentes níveis de erro.
   Critério: o gauge de error budget muda para amarelo abaixo de 25% e vermelho abaixo de 0%; o stat de burn rate muda para vermelho acima de 14.4×; a série histórica de 30 dias exibe a linha de SLO target horizontal; as queries usam recorded rules (não recalculam a janela de 30 dias bruta a cada refresh).
4. Versione um dashboard existente como código usando Terraform + grafana provider: exporte o JSON atual do dashboard, adapte-o como recurso grafana_dashboard com variáveis (service_name, datasource_uid), e aplique em um Grafana local via terraform apply. Faça uma mudança pequena (adicionar um panel), revise o diff do Terraform, e aplique.
   Critério: terraform plan mostra o dashboard como recurso a criar; após apply, o dashboard aparece no Grafana com o conteúdo correto; a mudança incremental produz um diff legível no terraform plan; o dashboard pode ser destruído e recriado a partir do código sem perda de configuração.
5. Conduza uma auditoria de anti-patterns em um conjunto de dashboards existentes (pode ser um projeto de exemplo público do Grafana): identifique pelo menos 4 anti-patterns da lista (vaidade, médias sem percentis, escala Y inadequada, sem variáveis de template, etc.), documente cada um com uma captura de tela ou descrição do panel problemático, e proponha a versão corrigida de cada um.
   Critério: pelo menos 4 anti-patterns identificados com justificativa específica (não genérica); cada anti-pattern tem a query ou configuração corrigida proposta; pelo menos um panel de latência com média foi substituído por P50/P95/P99; a auditoria está documentada em formato que poderia ser compartilhado com o time para guiar futuras revisões de dashboard.