Painéis

Painéis montados na interface do Grafana existem em um lugar só e desaparecem junto com quem os criou. Painéis 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 painéis 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 painel do Grafana em JSON, com pelo menos um campo title.

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

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

Tanto o JSON do painel quanto o formato "Export for sharing externally" (que embrulha o painel 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 painel. Uma visualização sem fonte de dados declarada passa a apontar para veloz-metrics. Isso significa que um painel 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 painel 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 painel 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 painel.
• 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 painel tem mais de 100 visualizações, contando as que ficam dentro de linhas.
• Há uma visualização 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 painéis 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 painéis 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 painel correspondente, identificado pelo caminho dentro do repositório:

Duas garantias importantes:

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

Limites

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

Onde aparecem

No painel, a aba Métricas de cada serviço tem o menu Dashboards, que lista os painéis provisionados do projeto e abre cada um no Grafana da sua organização.

Pelo terminal:

veloz obs dashboards

  Painéis 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 painel 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 do seu aplicativo
• Rastreamento: instrumente com OpenTelemetry
• veloz.json: referência completa da configuração