# Conectando o Grafana Este guia demonstra como conectar o Grafana ao **Consulta IoT** para visualizar dados de telemática e frota. O Grafana oferece poderosas capacidades de visualização para monitorar o status dos veículos, dados de sensores e outras métricas em tempo real. {% hint style="info" %} Este guia faz parte do **Consulta IoT** conjunto de documentação e cobre especificamente a conexão do Power BI ao seu data warehouse. Se você ainda está decidindo qual ferramenta de BI usar, consulte o [Selecionando ferramentas de BI](https://www.navixy.com/docs/analytics/datahub/connection-setup/selecting-bi-tools) visão geral. {% endhint %} Assista a um rápido vídeo de visão geral para ver o que é possível com a combinação **Consulta IoT**+Grafana (disponível em inglês e espanhol): {% tabs %} {% tab title="Inglês" %} {% embed url="" %} **Consulta IoT** + Visão geral e tutorial de configuração do Grafana. {% endembed %} {% endtab %} {% tab title="Español" %} {% embed url="" %} Descripción general y tutorial de configuración de **Consulta IoT** + Grafana. {% endembed %} {% endtab %} {% endtabs %} ## 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 customizadas 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 ao banco de dados * instância **Consulta IoT** ativa com credenciais de conexão ## Instalação e configuração O Grafana deve estar instalado em seu sistema antes de você poder conectar ao **Consulta IoT**. {% stepper %} {% step %} ### Instalar Grafana 1. Baixe e instale o Grafana a partir do site oficial:\ 2. Siga as instruções de instalação para o seu sistema operacional. {% endstep %} {% step %} ### 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 modelos são mantidos no [repositório bi-intergrations](https://github.com/SquareGPS/bi-intergrations) sob o `pasta grafana` Você pode clonar o repositório para acessar painéis prontos: ```bash git clone https://github.com/SquareGPS/bi-intergrations.git ``` Verifique a `pasta grafana` pasta para arquivos JSON de painel disponíveis. {% endstep %} {% endstepper %} ## Conexão com o banco de dados A seção Conexões no Grafana é onde você gerencia todas as integrações de fontes de dados. {% stepper %} {% step %} ### Acessar a aba Conexões Abra o Grafana e navegue até **Conexões** na barra lateral esquerda. **Consulta IoT** executa em PostgreSQL, portanto você precisa adicionar uma fonte de dados PostgreSQL para habilitar o Grafana a consultar seus dados de telemática. {% endstep %} {% step %} ### Adicionar fonte de dados PostgreSQL O plugin de fonte de dados PostgreSQL vem pré-instalado com o Grafana e fornece suporte nativo para conectar a bancos de dados PostgreSQL. Para adicionar a fonte de dados: 1. Na seção Conexões, pesquise por **PostgreSQL** 2. Clique **Adicionar nova fonte de dados** 3. A página de configuração do PostgreSQL será aberta {% endstep %} {% step %} ### Configurar parâmetros de conexão Seu **Consulta IoT** Os detalhes de conexão 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 **Consulta IoT** email de boas-vindas**.** **Referência de parâmetros de conexão** | Parâmetro | Campo de configuração | Descrição | | ---------------------- | --------------------- | ---------------------------------------------------------------------------------------------- | | Host | `Host` | Endereço do servidor de banco de dados fornecido nos seus **Consulta IoT** detalhes de conexão | | Porta | `Porta` | Padrão é 5432 para PostgreSQL | | Nome do banco de dados | `Banco de dados` | O nome do banco de dados atribuído a você | | Nome de usuário | `Usuário` | 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 | `Modo SSL` | Defina como `require` para conexões seguras | | Versão do PostgreSQL | `Versão` | Selecione **9.3** (configuração recomendada) | | {% endstep %} | | | {% step %} ### Configurar opções adicionais Além dos parâmetros essenciais de conexão, o Grafana oferece opções adicionais de configuração. Para a maioria dos usuários, os valores padrão são adequados e irão funcionar 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 equipamentos. Deixe todos os outros campos em seus valores padrão para a configuração inicial. Não é necessário ativar quaisquer chaves ou alternâncias adicionais. {% endstep %} {% step %} ### 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 **Consulta IoT** . Para verificar e salvar: 1. Nomeie sua conexão com um identificador descritivo (por exemplo, "**Consulta IoT** Produção" ou "Análise de Frota") 2. Clique **Salvar e Testar** para verificar sua conexão 3. Uma mensagem de sucesso em verde indica que a conexão está funcionando corretamente {% endstep %} {% endstepper %} ## Criando sua primeira visualização Construir sua primeira visualização ajuda você a entender como o Grafana consulta **Consulta IoT** 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. {% stepper %} {% step %} #### Criar um novo dashboard 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: 1. Navegue até **Dashboards** na barra lateral esquerda 2. Clique **Criar Dashboard** 3. Selecione **Adicionar visualização** 4. Escolha a fonte de dados PostgreSQL que você acabou de configurar {% endstep %} {% step %} #### Configurar a consulta O Grafana fornece dois modos de consulta: um Builder visual e um editor de Código. Para **Consulta IoT** conexões, o editor de Código dá controle total sobre consultas SQL e é recomendado para análise de dados de telemática. Para escrever sua consulta: 1. No editor de consultas, altere de **Builder** para **Code** modo 2. Digite sua consulta SQL diretamente Consulta de exemplo para visualização de dados de sensor: ```sql SELECT device_time AS time, value::numeric AS value, sensor_name FROM raw_telematics_data.inputs WHERE sensor_name = 'temperature' AND device_id = 12345 AND $__timeFilter(device_time) ORDER BY device_time ``` 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 dashboard à sua consulta. Para mais exemplos de consultas, consulte o [SQL Recipe Book](https://www.navixy.com/docs/analytics/example-queries). {% endstep %} {% step %} #### Definir o formato de visualização O formato de visualização determina como seus dados aparecem no dashboard. Formatos diferentes se adequam a tipos diferentes 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: 1. Clique **Executar consulta** para verificar se sua consulta retorna dados 2. Localize o seletor de tipo de visualização (geralmente no canto superior direito do painel) 3. Altere o formato de **Tabela** para **Séries temporais** ou seu formato preferido 4. Observe a exibição dos dados para garantir que apareça corretamente Visualizações de séries temporais exigem 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. {% endstep %} {% step %} #### Salvar sua visualização Salvar seu trabalho preserva a configuração da visualização e a torna disponível para referência futura. Salvamentos regulares são importantes — o Grafana não salva automaticamente as alterações, então você pode perder seu trabalho se navegar para fora sem salvar. Para salvar uma visualização: 1. Clique **Salve** 2. Forneça um nome descritivo para seu dashboard 3. Selecione ou crie uma pasta para organização 4. Confirme a operação de salvamento O dashboard agora está disponível na sua instância do Grafana e pode ser acessado pelo menu Dashboards. {% endstep %} {% endstepper %} ### 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. {% stepper %} {% step %} #### Acessar configurações de variáveis 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: 1. Abra seu dashboard 2. Clique no ícone de **Configurações** (ícone de engrenagem) no canto superior direito 3. Navegue até a **Variáveis** seção no painel esquerdo 4. A seção estará vazia se nenhuma variável tiver sido criada ainda {% endstep %} {% step %} #### 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 podem selecionar. Os valores da variável são preenchidos dinamicamente consultando seu **Consulta IoT** . Para criar uma variável: 1. Clique **Adicionar variável** 2. Configure as seguintes definições: 1. **Configurações gerais:** 1. **Nome**: `sensor_name` (use um identificador claro e descritivo sem espaços) 2. **Rótulo**: Mesmo que o nome para consistência, é o que os usuários veem no dashboard 3. **Tipo**: Selecione **Query** para preencher valores a partir do banco de dados 2. **Opções de consulta:** 1. **Fonte de dados**: Selecione seu **Consulta IoT** conexão PostgreSQL no menu suspenso 2. **Query**: Insira uma consulta SQL para popular os valores da variável Consulta de exemplo para listar todos os sensores de um dispositivo específico: ```sql SELECT DISTINCT sensor_name FROM raw_telematics_data.inputs WHERE device_id = 12345 ORDER BY sensor_name ``` 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. {% endstep %} {% step %} #### Aplicar variáveis nas consultas Depois que uma variável é criada, você precisa atualizar suas consultas de visualização para referenciá-la. Variáveis usam sintaxe especial com prefixo de cifrão, e o Grafana substitui automaticamente o valor selecionado ao executar as consultas. Para usar a variável: 1. Abra a visualização que você deseja tornar dinâmica 2. Edite a consulta 3. Substitua o valor codificado pelo referência da variável Exemplo de consulta atualizada usando a variável: ```sql SELECT device_time AS time, value::numeric AS value, sensor_name FROM raw_telematics_data.inputs WHERE sensor_name = '$sensor_name' AND device_id = 12345 AND $__timeFilter(device_time) ORDER BY device_time ``` Observe como `'temperature'` foi substituído por `'$sensor_name'`. As aspas são importantes para valores de string em SQL. {% endstep %} {% step %} #### 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 completar a configuração: 1. Clique **Aplicar** para salvar a configuração da variável 2. Clique **Salvar dashboard** para preservar todas as alterações 3. Retornar à visualização principal do dashboard 4. Localize o menu suspenso da variável no topo do dashboard 5. Selecione diferentes nomes de sensores no menu suspenso 6. Observe que a visualização é atualizada automaticamente com os dados do sensor selecionado Se a visualização não for atualizada quando você alterar a seleção da variável, verifique se o nome da variável na sua consulta corresponde exatamente ao nome da variável que você criou (nomes de variáveis diferenciam maiúsculas de minúsculas). {% endstep %} {% endstepper %} ### Importando dashboards pré-construídos Dashboards 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 melhores práticas para visualização, layout e otimização de consultas. No entanto, eles exigem configuração para conectar à sua específica **Consulta IoT** . {% stepper %} {% step %} #### Acessar a função de importação O recurso de importação do Grafana permite carregar configurações de dashboard a partir de arquivos JSON ou diretamente do Grafana.com usando IDs de dashboard. 1. Navegue até **Dashboards** 2. Clique **Novo** → **Importar** 3. Uma janela de upload aparecerá {% endstep %} {% step %} #### Importar o dashboard O processo de importação aceita configurações de dashboard em múltiplos formatos, dando-lhe flexibilidade sobre como carregar dashboards 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: 1. Clique **Enviar arquivo JSON** 2. Selecione o arquivo do dashboard 3. Forneça um nome e selecione a pasta de destino 4. Clique **Importar** Aguarde o template do dashboard terminar o upload. Uma vez concluído, o dashboard aparecerá, mas ainda não exibirá dados porque continua conectado à fonte de dados original usada quando o template foi criado. {% endstep %} {% step %} #### 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 **Consulta IoT** dados. Você deve atualizar cada visualização para usar sua conexão PostgreSQL. **Consulta IoT** Para atualizar visualizações: Abra o dashboard importado 1. Editar 2. Clique **no primeiro painel de visualização (procure o ícone de editar ou o menu de três pontos)** No editor de consultas, localize o seletor de fonte de dados 3. Altere a fonte de dados da origem original do template para sua 4. conexão PostgreSQL **Consulta IoT** para verificar se a visualização recupera dados com sucesso 5. Clique **Executar consulta** para preservar as alterações 6. Clique **Salve** Repita esse processo para cada painel de visualização no dashboard 7. Salve seu trabalho frequentemente durante esse processo. Você pode ter múltiplas visualizações para atualizar, e salvar após cada uma garante que você não perca o progresso. {% hint style="info" %} Atualizar variáveis do dashboard {% endhint %} {% endstep %} {% step %} #### 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 seu Para atualizar variáveis: **Consulta IoT** . Abra 1. Você verá uma lista de todas as variáveis usadas no dashboard **Configurações** → **Variáveis** 2. no primeiro item de variável 3. Clique **no primeiro painel de visualização (procure o ícone de editar ou o menu de três pontos)** Localize o 4. menu suspenso na seção Opções de consulta **Fonte de dados** Altere para sua 5. PostgreSQL **Consulta IoT** para verificar se a visualização recupera dados com sucesso 6. Verifique se a pré-visualização na parte inferior mostra os valores esperados do seu banco de dados 7. Clique **Aplicar** para confirmar as alterações 8. Repita para cada variável na lista Após atualizar todas as variáveis, salve o dashboard novamente. As variáveis agora devem se preencher com valores do seu **Consulta IoT** . {% endstep %} {% step %} #### Verificar funcionalidade do dashboard Depois de atualizar todas as visualizações e variáveis, verifique se tudo funciona corretamente em conjunto. Essa verificação final garante que o dashboard está totalmente funcional e pronto para uso regular. Para verificar: 1. Salve o dashboard uma última vez usando **Ctrl+S** ou o **Salve** botão 2. Atualize completamente a página do navegador (ou use **F5**) 3. Verifique se todas as visualizações exibem dados corretamente 4. Teste cada menu suspenso de variável para garantir que ele se preencha com valores 5. Selecione diferentes valores de variável e confirme que as visualizações são atualizadas de acordo 6. Experimente diferentes intervalos de tempo usando o seletor de tempo Se alguma visualização permanecer vazia ou mostrar erros, retorne ao modo de edição e verifique a configuração da fonte de dados e da consulta desses painéis específicos. {% endstep %} {% endstepper %} ## 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 seus **Consulta IoT** detalhes. Verifique se host, porta, nome do banco, nome de usuário e senha estão corretos. **Erro de firewall**: Garanta que sua rede permita conexões ao host e porta especificados. Contate o administrador de 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 checando o inspetor de consultas (clique no botão "Query inspector" no editor de painel). Garanta que o intervalo de tempo selecionado inclua períodos em que existam dados no seu banco. Confirme que a fonte de dados está corretamente selecionada e conectada. Verifique se 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 checando a pré-visualização na página de configuração da variável. Assegure que a referência da variável na sua consulta use a sintaxe correta (`$variable_name`) sem erros de digitação. Verifique se a variável foi salva corretamente 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 em colunas frequentemente consultadas como `device_time` e `device_id`. Limite intervalos de dados usando filtros de tempo de forma mais restritiva. Otimize a estrutura da consulta selecionando apenas colunas necessárias em vez de usar `SELECT *`. Consulte o [SQL Recipe Book](https://www.navixy.com/docs/analytics/example-queries) para exemplos de otimização de desempenho e padrões de consulta comprovados. **Incompatibilidade de formato**: Garanta que sua consulta retorne dados no formato esperado pelo tipo de visualização. 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 tempo e dados numéricos. Verifique a documentação do Grafana para requisitos específicos de cada tipo de visualização. ### Problemas na importação **Dados faltando após 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 de esquema (`raw_business_data` ou `raw_telematics_data`) especificados nas consultas estão corretos para sua **Consulta IoT** instância. Assegure que nomes de tabelas e colunas correspondam à estrutura real do seu banco. **Dashboard apresenta 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 atentamente — 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 **Consulta IoT** esquema (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, 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. Garanta 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 **Consulta IoT** instância: * Explore os schemas de dados disponíveis revisando o [Visão geral do esquema](https://www.navixy.com/docs/analytics/pt-br/iot-query/schema-overview) para entender a estrutura dos dados, relacionamentos 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 aprender a estrutura dos dados e evitar problemas de desempenho. * Reveja o [SQL Recipe Book](https://www.navixy.com/docs/analytics/pt-br/example-queries) 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 propósitos: monitoramento em tempo real, análise histórica, resumos executivos e relatórios operacionais. ### Suporte Para perguntas técnicas ou assistência com **Consulta IoT** conexões, contate o suporte em .