Conectando o Grafana
Este guia demonstra como conectar o Grafana ao DataHub para visualizar dados de telemática e de frota. O Grafana fornece poderosas capacidades de visualização para monitorar o status dos veículos, dados de sensores e outras métricas em tempo real.
Assista a um vídeo rápido para ver o que é possível com a combinação DataHub+Grafana (disponível em inglês e espanhol):
Recursos do painel
Visualização de dados de sensores em tempo real
Análise de séries temporais com intervalos de tempo personalizáveis
Filtragem dinâmica usando variáveis
Suporte para múltiplas fontes de dados
Gráficos e diagramas interativos
Construção de consultas personalizadas com SQL
Requisitos técnicos
Grafana 9.3 ou posterior
Plugin de fonte de dados PostgreSQL (incluído por padrão)
Acesso à Internet para conexão com o banco de dados
Instância ativa do DataHub com credenciais de conexão
Instalação e configuração
O Grafana deve estar instalado em seu sistema antes de você poder conectar-se ao DataHub.
Instalar o Grafana
Faça o download e instale o Grafana a partir do site oficial: https://grafana.com/grafana/download
Siga as instruções de instalação para o seu sistema operacional.
Baixar modelos de painel (opcional)
Modelos de painel pré-construídos estão disponíveis para ajudá-lo a começar rapidamente sem construir visualizações do zero. Esses templates são mantidos no repositório bi-intergrations sob o pasta grafana Você pode clonar o repositório para acessar painéis prontos:
Verifique a pasta grafana pasta para arquivos JSON de painel disponíveis.
Conexão com o banco de dados
A seção Connections no Grafana é onde você gerencia todas as integrações de fontes de dados. O DataHub executa em PostgreSQL, portanto você precisará adicionar uma fonte de dados PostgreSQL para permitir que o Grafana consulte seus dados de telemática.
Adicionar fonte de dados PostgreSQL
O plugin de fonte de dados PostgreSQL vem pré-instalado com o Grafana e fornece suporte nativo para conectar-se a bancos de dados PostgreSQL.
Para adicionar a fonte de dados:
Na seção Connections, pesquise por PostgreSQL
Clique em Add new data source
A página de configuração do PostgreSQL será aberta
Configurar parâmetros de conexão
Os detalhes de conexão do seu DataHub contêm todas as informações necessárias para estabelecer uma conexão segura. Esses parâmetros são exclusivos da sua instância e garantem que o Grafana possa acessar seus dados de telemática.
Localize seus parâmetros de conexão na sua conta Navixy e no e-mail de boas-vindas do DataHub.
Referência de parâmetros de conexão
Host
Host
Endereço do servidor de banco de dados fornecido nos detalhes de conexão do seu DataHub
Porta
Porta
O padrão é 5432 para PostgreSQL
Nome do banco de dados
Database
O nome do banco de dados atribuído a você
Nome de usuário
User
Seu nome de usuário do banco de dados (referido como "database user" nos detalhes de conexão)
Senha
Senha
Sua senha segura do banco de dados
Modo SSL
SSL Mode
Defina como require para conexões seguras
Versão do PostgreSQL
Version
Selecione 9.3 (configuração recomendada)
Configurar configurações adicionais
Além dos parâmetros de conexão essenciais, o Grafana oferece opções de configuração adicionais. Para a maioria dos usuários, os valores padrão são adequados e funcionarão corretamente sem modificação. Você pode ajustar essas configurações posteriormente com base nos requisitos de segurança da sua organização, restrições de infraestrutura ou necessidades específicas de equipamento.
Deixe todos os outros campos com seus valores padrão para a configuração inicial. Não é necessário habilitar switches ou alternadores adicionais.
Testar a conexão
Testar a conexão antes de salvar garante que todos os parâmetros estejam corretos e que o Grafana possa se comunicar com sucesso com sua instância do DataHub.
Para verificar e salvar:
Dê um nome à sua conexão com um identificador descritivo (por exemplo, "DataHub Production" ou "Fleet Analytics")
Clique em Save & Test para verificar sua conexão
Uma mensagem de sucesso verde indica que a conexão está funcionando corretamente
Criando sua primeira visualização
Construir sua primeira visualização ajuda a entender como o Grafana consulta o DataHub e exibe dados de telemática. Esse processo envolve criar um painel, adicionar um painel (panel), configurar uma consulta e selecionar um formato de visualização apropriado.
Criar um novo dashboard
Painéis (Dashboards) no Grafana servem como contêineres para múltiplas visualizações. Criar um dashboard dedicado ajuda a organizar visualizações relacionadas e fornece um local central para monitorar aspectos específicos das operações da sua frota.
Para criar um dashboard:
Navegue até Dashboards na barra lateral esquerda
Clique em Create Dashboard
Selecione Adicionar visualização
Escolha a fonte de dados PostgreSQL que você acabou de configurar
Configurar a consulta
O Grafana fornece dois modos de consulta: um Builder visual e um editor de Código. Para conexões com o DataHub, o editor de Código fornece controle total sobre consultas SQL e é recomendado para análise de dados de telemática.
Para escrever sua consulta:
No editor de consultas, altere de Builder para Code modo
Insira sua consulta SQL diretamente
Exemplo de consulta para visualização de dados de sensores:
A consulta inclui um componente de tempo (device_time AS time) que é essencial para visualizações de séries temporais. A $__timeFilter() função é uma macro do Grafana que aplica automaticamente o intervalo de tempo selecionado no painel à sua consulta.
Para mais exemplos de consultas, consulte o SQL Recipe Book.
Definir formato de visualização
O formato de visualização determina como seus dados aparecem no painel. Diferentes formatos servem a diferentes tipos de dados—séries temporais funcionam bem para leituras de sensores ao longo do tempo, enquanto tabelas são melhores para registros detalhados.
Para configurar o formato:
Clique em Executar consulta para verificar se sua consulta retorna dados
Localize o seletor de tipo de visualização (geralmente no canto superior direito do painel)
Altere o formato de Table para Time series ou seu formato preferido
Observe a exibição dos dados para garantir que apareça corretamente
Visualizações de séries temporais requerem uma coluna de tempo e valores numéricos para funcionar corretamente. Sua consulta deve retornar dados no formato apropriado para o tipo de visualização selecionado.
Salvar sua visualização
Salvar sua visualização
Para salvar uma visualiyation:
Clique em Save
Forneça um nome descritivo para o seu dashboard
Selecione ou crie uma pasta para organização
Confirme a operação de salvamento
O dashboard agora está disponível em sua instância do Grafana e pode ser acessado através do menu Dashboards.
Trabalhando com variáveis
Variáveis são um dos recursos mais poderosos do Grafana para criar dashboards dinâmicos e interativos. Em vez de codificar valores específicos como nomes de sensores ou IDs de dispositivos em suas consultas, as variáveis permitem que os usuários selecionem diferentes valores a partir de menus suspensos sem editar o SQL subjacente. Isso torna os dashboards mais flexíveis e fáceis de usar.
Acessar configurações de variáveis
As variáveis são configuradas no nível do dashboard e se aplicam a todas as visualizações dentro desse dashboard. Você precisa acessar as configurações do dashboard para criar e gerenciar variáveis.
Para começar:
Abra seu dashboard
Clique no ícone Settings (ícone de engrenagem) no canto superior direito
Navegue até a Variables seção no painel esquerdo
A seção estará vazia se nenhuma variável tiver sido criada ainda
Configurar uma variável
Cada variável precisa de um nome, uma fonte de dados e uma consulta que retorne os valores possíveis que os usuários possam selecionar. Os valores da variável são preenchidos dinamicamente consultando sua instância do DataHub.
Para criar uma variável:
Clique em Add variable
Configure as seguintes configurações:
Configurações gerais:
Name:
sensor_name(use um identificador claro e descritivo sem espaços)Label: Igual ao nome para consistência, isto é o que os usuários veem no dashboard
Type: Selecione Query para popular valores a partir do banco de dados
Opções de consulta:
Data source: Selecione sua conexão PostgreSQL do DataHub no menu suspenso
Query: Insira uma consulta SQL para popular os valores da variável
Exemplo de consulta para listar todos os sensores de um dispositivo específico:
Após inserir a consulta, o Grafana a executa imediatamente e exibe uma pré-visualização dos valores retornados na parte inferior da página de configuração. Isso confirma que sua consulta está funcionando corretamente e mostra quais opções estarão disponíveis no menu suspenso.
Aplicar variáveis em consultas
Uma vez criada a variável, você precisa atualizar suas consultas de visualização para referenciá-la. As variáveis usam uma sintaxe especial com prefixo de cifrão, e o Grafana substitui automaticamente o valor selecionado ao executar as consultas.
Para usar a variável:
Abra a visualização que deseja tornar dinâmica
Edite a consulta
Substitua o valor codificado pelo referência da variável
Exemplo de consulta atualizada usando a variável:
Observe como 'temperature' foi substituído por '$sensor_name'. As aspas são importantes para valores de texto em SQL.
Salvar e testar
Testar a variável garante que ela funcione corretamente e atualize as visualizações conforme esperado. Certifique-se de salvar seu trabalho em cada etapa para evitar perder alterações de configuração.
Para concluir a configuração:
Clique em Apply para salvar a configuração da variável
Clique em Save dashboard para preservar todas as alterações
Retorne à visualização principal do dashboard
Localize o menu suspenso da variável no topo do dashboard
Selecione diferentes nomes de sensores no menu suspenso
Observe que a visualização atualiza automaticamente com os dados do sensor selecionado
Se a visualização não atualizar quando você alterar a seleção da variável, verifique se o nome da variável em sua consulta corresponde exatamente ao nome da variável que você criou (os nomes de variáveis diferenciam maiúsculas de minúsculas).
Importando painéis pré-construídos
Painéis pré-construídos fornecem uma maneira rápida de começar a visualizar seus dados sem construir tudo do zero. Esses dashboards são projetados por usuários experientes e incluem boas práticas para visualização, layout e otimização de consultas. No entanto, eles exigem configuração para se conectar à sua instância do DataHub.
Importar o dashboard
O processo de importação aceita configurações de dashboard em múltiplos formatos, dando-lhe flexibilidade em como carregar painéis pré-construídos.
Você pode importar dashboards usando:
ID do dashboard do Grafana.com
Arquivo JSON baixado do repositório bi-intergrations
Modelo JSON colado diretamente
Se estiver usando um arquivo JSON:
Clique em Upload do arquivo JSON
Selecione o arquivo do dashboard
Forneça um nome e selecione a pasta de destino
Clique em Import
Aguarde o modelo do dashboard terminar o upload. Uma vez concluído, o dashboard aparecerá, mas ainda não exibirá dados porque está conectado à fonte de dados original usada quando o template foi criado.
Atualizar conexões de fonte de dados
Esta é uma etapa crítica. Dashboards importados estão inicialmente conectados a fontes de dados externas que não têm acesso aos seus dados do DataHub. Você deve atualizar cada visualização para usar sua conexão PostgreSQL do DataHub.
Para atualizar visualizações:
Abra o dashboard importado
Clique em Edit no primeiro painel de visualização (procure o ícone de edição ou o menu de três pontos)
No editor de consultas, localize o seletor de fonte de dados
Altere a fonte de dados da origem original do template para sua conexão PostgreSQL do DataHub
Clique em Executar consulta para verificar se a visualização recupera dados com sucesso
Clique em Save para preservar as alterações
Repita esse processo para cada painel de visualização no dashboard
Atualizar variáveis do dashboard
Muitos dashboards pré-construídos usam variáveis para filtragem e interatividade. Essas variáveis também estão conectadas à fonte de dados original e devem ser atualizadas para consultar sua instância do DataHub.
Para atualizar variáveis:
Abra Settings → Variables
Você verá uma lista de todas as variáveis usadas no dashboard
Clique em Edit no primeiro variável
Localize o Data source menu suspenso na seção Opções de consulta
Altere-o para sua conexão PostgreSQL do DataHub
Verifique se a pré-visualização na parte inferior mostra os valores esperados do seu banco de dados
Clique em Apply para confirmar as alterações
Repita para cada variável na lista
Após atualizar todas as variáveis, salve o dashboard novamente. As variáveis agora devem ser preenchidas com valores da sua instância do DataHub.
Verificar a funcionalidade do dashboard
Depois de atualizar todas as visualizações e variáveis, verifique se tudo funciona corretamente em conjunto. Esta verificação final garante que o dashboard esteja totalmente funcional e pronto para uso regular.
Para verificar:
Salve o dashboard uma última vez usando Ctrl+S ou o Save botão
Atualize completamente a página do navegador (ou use F5)
Verifique se todas as visualizações exibem dados corretamente
Teste cada menu suspenso de variável para garantir que ele seja preenchido com valores
Selecione diferentes valores de variável e confirme que as visualizações atualizam de acordo
Experimente diferentes intervalos de tempo usando o seletor de tempo
Se alguma visualização permanecer vazia ou exibir erros, retorne ao modo de edição e verifique a configuração da fonte de dados e da consulta para esses painéis específicos.
Solução de problemas
Problemas de conexão com o banco de dados
Erro de conexão: Verifique se as credenciais e os parâmetros de conexão correspondem exatamente aos detalhes do seu DataHub. Verifique se host, porta, nome do banco de dados, nome de usuário e senha estão corretos.
Erro de firewall: Certifique-se de que sua rede permite conexões para o host e a porta especificados. Contate o administrador da sua rede se as tentativas de conexão estiverem sendo bloqueadas.
Erro de SSL/TLS: Verifique se o modo SSL está definido como require e se sua instância do Grafana suporta conexões SSL.
Problemas de consulta e visualização
Visualização vazia: Primeiro, verifique se a consulta realmente retorna dados verificando o query inspector (clique no botão "Query inspector" no editor do painel). Garanta que o intervalo de tempo selecionado inclua períodos em que existam dados no seu banco de dados. Confirme se a fonte de dados está corretamente selecionada e conectada. Verifique se os nomes de tabelas e colunas na sua consulta correspondem à estrutura real do esquema.
Variável não funcionando: Verifique se a consulta da variável retorna valores verificando a pré-visualização na página de configuração da variável. Certifique-se de que a referência da variável em sua consulta use a sintaxe correta ($variable_name) sem erros de digitação. Verifique se a variável está corretamente salva e aplicada ao dashboard. Se o menu suspenso da variável estiver vazio, revise a consulta SQL da variável em busca de erros.
Desempenho lento de consultas: Considere adicionar índices no banco de dados para colunas consultadas frequentemente, tais como device_time e device_id. Limite os intervalos de dados usando filtros de tempo de forma mais restritiva. Otimize a estrutura da consulta selecionando apenas as colunas necessárias em vez de usar SELECT *. Consulte o SQL Recipe Book para exemplos de otimização de desempenho e padrões de consulta comprovados.
Incompatibilidade de formato: Certifique-se de que sua consulta retorne dados no formato esperado pelo tipo de visualização selecionado. Painéis de séries temporais exigem uma coluna com alias como time e colunas de valores numéricos. Painéis de tabela aceitam qualquer estrutura de colunas. Painéis de gráfico precisam de dados de tempo e numéricos. Consulte a documentação do Grafana para requisitos específicos de cada tipo de visualização.
Problemas de importação
Dados ausentes após a importação: Verifique se as conexões das fontes de dados foram atualizadas para todos os painéis e variáveis. Não pule nenhum painel durante o processo de atualização. Verifique se os nomes dos schemas (raw_business_data ou raw_telematics_data) especificados nas consultas estão corretos para sua instância do DataHub. Certifique-se de que os nomes de tabelas e colunas correspondam à estrutura real do seu banco de dados.
O painel mostra erros: Abra o editor de consultas de cada painel e clique em "Query inspector" para ver mensagens de erro detalhadas. Revise as mensagens de erro cuidadosamente—elas frequentemente indicam problemas específicos como colunas ausentes, tipos de dados incorretos ou erros de sintaxe. Garanta que os nomes de campos nas consultas correspondam exatamente ao seu esquema do DataHub (os nomes de campos diferenciam maiúsculas de minúsculas). Verifique se os tipos de dados retornados pelas consultas são compatíveis com o tipo de visualização.
Variáveis não populando: Verifique se você atualizou a fonte de dados para cada variável, e não apenas para os painéis de visualização. Confirme que as consultas das variáveis estão sintaticamente corretas e retornam dados quando executadas diretamente. Certifique-se de que o tipo da variável esteja definido como "Query" em vez de "Custom" ou outros tipos.
Próximos passos
Após conectar com sucesso o Grafana à sua instância do DataHub:
Explore os schemas de dados disponíveis revisando a Visão geral do esquema para entender a estrutura dos dados, relações entre tabelas e campos disponíveis.
Comece com consultas simples focadas em entidades de negócio específicas antes de construir dashboards complexos; isso ajuda a conhecer a estrutura dos dados e evitar problemas de desempenho.
Revise o SQL Recipe Book para padrões de consulta comprovados e técnicas de otimização, e exemplos de cenários comuns de análises de telemática
Experimente diferentes tipos de visualização (séries temporais, tabelas, gauges, painéis stat) para encontrar a melhor representação para seus dados e casos de uso específicos
Considere criar múltiplos dashboards para diferentes finalidades: monitoramento em tempo real, análise histórica, resumos executivos e relatórios operacionais.
Suporte
Para perguntas técnicas ou assistência com conexões do DataHub, entre em contato com o suporte em [email protected].
Atualizado
Isto foi útil?