Ache as armadilhas de importação antes de publicar o dashboard.

22 regras sobre um parse real do dashboard: 7 erros, 11 avisos e 4 notas. Os erros são os que mudam o que o Grafana faz — uma variável de template que nada declara, um placeholder ${DS_…} sem bloco __inputs, um painel AngularJS que não renderiza nada no Grafana 11–12, dois painéis com o mesmo id, um repeat sobre uma variável inexistente, um painel sem type, e uma schemaVersion tão antiga que o JSON e a renderização são dois dashboards diferentes. Os avisos são os problemas de portabilidade e de revisão: um uid ausente, um id de banco deixado em um arquivo commitado, uma datasource referenciada por nome, um painel graph ou singlestat obsoleto, um painel invisível de largura zero, um intervalo de tempo padrão de mais de um ano, um refresh abaixo de dez segundos. Cada regra tem a própria subseção nesta página, e os chips de regra do playground linkam direto para ela.

Não. O parser e todas as regras são JavaScript rodando na sua aba — não há servidor, chamada de API nem log, então 0 bytes são enviados. Isso importa mais aqui do que na maioria das ferramentas: o JSON de um dashboard é um mapa do seu parque interno. Nomes de métricas, uids de datasources, hostnames em formatos de legenda, nomes de serviço em queries de variável, às vezes uma URL interna em um link de painel. É exatamente o arquivo que você não deveria colar em um formatador online qualquer.

Não, e a ferramenta diz isso em vez de insinuar o contrário. O schema de dashboard do Grafana é grande, versionado e continua em movimento, então uma checagem parcial apresentada como checagem de schema seria pior do que nenhuma. O que ela faz é um lint estrutural: lê as formas que quebram importações e revisões — variáveis, referências de datasource, tipos de painel, ids, layout, tempo e refresh — e nomeia o caminho JSON de cada achado. Não parseia PromQL, não conhece seus plugins e não fala com nenhum Grafana. A lista completa do que ela cala de propósito está acima, em “O que ela não aponta de propósito”.

Porque o arquivo veio de “Export for sharing externally”. Essa exportação troca cada referência de datasource por um placeholder — ${DS_PROMETHEUS} — e adiciona um bloco “__inputs” descrevendo o que cada placeholder precisa. Só o diálogo Dashboards → Import lê esse bloco e pede que você escolha uma datasource real. Provisionar o mesmo arquivo, dar POST na API ou deixá-lo em uma pasta sincronizada por Git pula o diálogo por completo: o placeholder sobrevive no dashboard salvo e todos os painéis falham em resolvê-lo. Ou você importa pelo diálogo, ou substitui o { type, uid } real antes de provisionar. Este linter reporta o placeholder como erro nos dois casos, porque o arquivo não é provisionável como está.

O uid é o identificador que você escolhe. Ele faz parte da URL do dashboard, é o que provisionamento e API endereçam, e deve viver no controle de versão junto do JSON. O id é um número de linha no banco de uma instância específica do Grafana — fora dela não significa nada. Um arquivo com uid atualiza o mesmo dashboard a cada importação; um sem uid cria uma cópia nova toda vez. Um arquivo com id desatualizado falha na importação ou acerta um dashboard que não tem nada a ver com o seu, e é por isso que uma exportação deveria trazer “id”: null.

Os painéis de núcleo graph, singlestat e table-old são migrados automaticamente quando o dashboard carrega, então continuam funcionando — mas o JSON no seu repositório não é migrado, o que significa que o arquivo que você revisa e o painel que o Grafana renderiza são duas coisas diferentes. Salve o dashboard de novo a partir do Grafana 9 ou mais novo para escrever a migração no arquivo. PLUGINS de painel AngularJS são outra história: grafana-piechart-panel, grafana-worldmap-panel e os demais não têm migração automática, e o suporte a Angular foi marcado como obsoleto no Grafana 9 e removido ao longo do Grafana 11–12, então esses painéis não renderizam nada e precisam ser trocados à mão.

O conjunto de regras está fixado em grafana-12 / schemaVersion 41, impresso nesta página e em todo relatório copiado, para que um relatório nunca seja ambíguo sobre o que o verificou. As regras sensíveis a versão são escritas como faixas — “Grafana 9–12”, “removido ao longo do Grafana 11–12” — em vez de um release exato, porque a sua instância está perto deste ponto e não exatamente nele. Se a schemaVersion do seu dashboard for maior que 41, você recebe uma NOTA dizendo isso e os achados específicos de schema ficam marcados como indicativos. Um schema desconhecido é um limite deste linter, não um defeito do seu dashboard, então ele nunca é reportado como erro.

Porque o Grafana não falha: ele não interpola nada e roda a query com o texto literal dentro. Um seletor PromQL {env="$env"} não casa com nenhuma série, então o painel fica vazio; um seletor com casamento por regex pode casar com MUITO mais séries do que você queria, então o painel fica cheio e errado. Nenhum dos dois casos produz mensagem em lugar algum da interface. A única exceção que este linter abre é uma referência dentro de uma string que parece uma expressão regular, onde “$” também é uma âncora de fim de linha: ali o achado cai para aviso, porque aquele “$env” que você escreveu pode realmente ter sido uma âncora seguida de texto.

Até 5.000.000 caracteres, o que cobre um dashboard gerado com vários milhares de painéis; um de 500 painéis é analisado em poucos milissegundos. Acima desse limite ele recusa com uma mensagem em vez de congelar sua aba, porque uma entrada desse tamanho é um log ou um arquivo compactado, não um dashboard. Os achados também têm teto: 50 por regra e 400 no total, e o painel informa o teto e o número real sempre que um deles se aplica — uma lista truncada que não dissesse que está truncada seria exatamente o tipo de erro silencioso que esta ferramenta existe para pegar.