Dashboards

Dashboards montados na interface do Grafana existem em um lugar só e desaparecem junto com quem os criou. Dashboards versionados no repositório passam por code review, acompanham a branch e voltam com o git revert.

A Veloz provisiona, a cada deploy, uma pasta de dashboards do seu repositório para dentro do Grafana da sua organização.

Configuração

dashboards é configurado uma vez por projeto, não por serviço:

{
  "version": "1.0",
  "project": {
    "id": "proj_abc123",
    "name": "loja"
  },
  "observability": {
    "dashboards": "./dashboards"
  },
  "services": {
    "apps/api": {
      "id": "svc_api456",
      "name": "loja-api",
      "type": "web",
      "root": "apps/api"
    }
  }
}

O caminho é relativo à raiz do repositório. Precisa ser um diretório (não a raiz), não pode sair do repositório com .. e aceita apenas letras, números, ponto, hífen, sublinhado e barra.

A leitura não é recursiva: só entram os arquivos .json diretamente dentro da pasta. Subpastas são ignoradas.

loja/
├── veloz.json
├── dashboards/
│   ├── visao-geral.json      ← provisionado
│   ├── filas.json            ← provisionado
│   └── rascunhos/
│       └── teste.json        ← ignorado
└── apps/

Formato aceito

Cada arquivo é um dashboard do Grafana em JSON, com pelo menos um campo title.

A forma mais simples de criar o primeiro é exportar um dashboard que você já montou:

1. No Grafana, abra o dashboard e escolha Share e depois Export.
2. Salve o JSON como um arquivo dentro da pasta de dashboards.
3. Faça commit e rode veloz deploy.

Tanto o JSON do dashboard quanto o formato "Export for sharing externally" (que embrulha o dashboard em { "dashboard": ..., "meta": ... }) são aceitos. A Veloz desembrulha automaticamente.

Fontes de dados

Sua organização tem três fontes de dados, sempre com os mesmos identificadores:

A Veloz reescreve toda referência de fonte de dados do arquivo para uma dessas três, deduzindo pelo tipo declarado no dashboard. Um painel sem fonte de dados declarada passa a apontar para veloz-metrics. Isso significa que um dashboard exportado de outro Grafana funciona sem edição manual dos identificadores.

Seletores de fonte de dados (variáveis de template do tipo datasource) são removidos: eles fariam o mesmo dashboard renderizar dados diferentes para cada pessoa.

Ajustes automáticos

Ao provisionar, a Veloz:

• Substitui os campos de identidade do arquivo (id, uid, version) e as referências de pasta por valores próprios, para que dois projetos possam publicar o mesmo dashboard sem colisão.
• Fixa as fontes de dados nos identificadores acima.
• Acrescenta as etiquetas veloz:managed e veloz:project:<projeto>. Suas etiquetas são preservadas, até 10 por dashboard.
• Eleva o intervalo de atualização automática para no mínimo 10 segundos.
• Remove blocos de alerta antigos. Alertas não fazem parte desta versão.

O que é recusado

Um arquivo é recusado quando:

• O JSON é inválido, ou não é um objeto.
• Não há title, ou o título passa de 128 caracteres.
• O campo panels não é uma lista.
• O dashboard tem mais de 100 painéis, contando os que ficam dentro de linhas.
• Há um painel de texto em modo HTML. Use o modo markdown.
• Há um link com esquema javascript:, data: ou vbscript:.
• O arquivo passa de 256 KB.

Importante: a recusa é por arquivo e nunca derruba o deploy. Os demais dashboards do projeto são provisionados normalmente, e o motivo da recusa aparece no log do deploy (veloz builds logs <id>).

Validação local

Valide antes de fazer o deploy, para que a falha seja visível em vez de silenciosa:

veloz obs validate

  Validando dashboards em ./dashboards

  ✗ ./dashboards/api.json          JSON inválido na linha 42
  ✓ ./dashboards/filas.json        6 KB  4 painéis
  ✓ ./dashboards/visao-geral.json  12 KB  8 painéis

1 de 3 arquivo(s) com problema. Corrija antes do deploy.
  ./dashboards/api.json: JSON inválido na linha 42

O comando roda inteiramente na sua máquina, sem autenticação e sem chamar o servidor, o que o torna útil na sua CI: ele sai com código 1 quando algum arquivo falha.

A validação local pega os erros mais comuns, que são JSON inválido, arquivo sem title e arquivo grande demais. As regras restantes da seção O que é recusado são aplicadas no momento do deploy.

Atualização e remoção

Cada arquivo tem um dashboard correspondente, identificado pelo caminho dentro do repositório:

Duas garantias importantes:

• Dashboards criados por você na interface do Grafana nunca são tocados. A remoção só alcança dashboards que a própria Veloz provisionou para aquele projeto.
• Se você editar um dashboard provisionado direto no Grafana, a Veloz para de sobrescrevê-lo. A edição manual é preservada. Para voltar ao controle do repositório, apague o dashboard no Grafana e faça um novo deploy.

Limites

Um dashboard exportado do Grafana costuma ficar em torno de 100 KB, então os limites raramente aparecem em uso normal.

Onde aparecem

No app da Veloz, a aba Métricas de cada serviço tem uma linha Dashboards no card de estado, com a contagem de dashboards provisionados e há quanto tempo foi a última atualização. Os links para o Grafana da sua organização saem de veloz obs dashboards.

Pelo terminal:

veloz obs dashboards

  Dashboards publicados

  Visão geral da loja   https://grafana.onveloz.com/d/vzd-a1b2c3d4?orgId=7
                        ./dashboards/visao-geral.json
  Filas                 https://grafana.onveloz.com/d/vzd-e5f6a7b8?orgId=7
                        ./dashboards/filas.json
  Pagamentos            https://grafana.onveloz.com/d/vzd-c9d0e1f2?orgId=7
                        ./dashboards/pagamentos.json

Cada dashboard vem com o link e, abaixo, o arquivo do repositório que o originou.

Próximos passos

• Observabilidade: visão geral e diagnósticos
• Métricas customizadas: exponha as métricas da sua aplicação
• Traces: instrumente com OpenTelemetry
• veloz.json: referência completa da configuração