# Conectando o Grafana Este guia demonstra como conectar o Grafana ao **IoT Query** para visualizar dados de telemetria e de frota. O Grafana oferece poderosos recursos de visualização para monitorar o status do veículo, dados de sensores e outras métricas em tempo real. {% hint style="info" %} Este guia faz parte do **IoT Query** conjunto de documentação e aborda especificamente a conexão do Power BI ao seu data warehouse. Se você ainda estiver decidindo qual ferramenta de BI usar, consulte a [Seleção de ferramentas de BI](https://www.navixy.com/docs/analytics/datahub/connection-setup/selecting-bi-tools) visão geral. {% endhint %} Assista a uma breve visão geral em vídeo para ver o que é possível com **IoT Query**+ a combinação Grafana (disponível em inglês e espanhol): {% tabs %} {% tab title="Inglês" %} {% embed url="" %} **IoT Query** + visão geral do Grafana e tutorial de configuração. {% endembed %} {% endtab %} {% tab title="Español" %} {% embed url="" %} Descripción general y tutorial de configuración de **IoT Query** + Grafana. {% endembed %} {% endtab %} {% endtabs %} ## Recursos do dashboard * 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 várias fontes de dados * Gráficos e diagramas interativos * Criação de consultas personalizadas com SQL ## Requisitos técnicos * Grafana 9.3 ou posterior * Plug-in de fonte de dados PostgreSQL (incluído por padrão) * Acesso à Internet para conexão com o banco de dados * Ativo **IoT Query** instância com credenciais de conexão ## Instalação e configuração O Grafana deve estar instalado no seu sistema antes que você possa se conectar ao **IoT Query**. {% stepper %} {% step %} #### Instalar o Grafana 1. Baixe e instale o Grafana no site oficial:\ 2. Siga as instruções de instalação para o seu sistema operacional. {% endstep %} {% step %} #### Baixar modelos de dashboard (opcional) Modelos de dashboard prontos estão disponíveis para ajudá-lo a começar rapidamente, sem criar visualizações do zero. Esses modelos são mantidos no [repositório bi-intergrations](https://github.com/SquareGPS/bi-intergrations) na `pasta grafana` . Você pode clonar o repositório para acessar dashboards prontos: ```bash git clone https://github.com/SquareGPS/bi-intergrations.git ``` Verifique a `pasta grafana` pasta para os arquivos JSON de dashboard disponíveis. {% endstep %} {% endstepper %} ## Conexão com o banco de dados A seção Connections no Grafana é onde você gerencia todas as integrações de fontes de dados. {% stepper %} {% step %} #### Acesse a aba Connections Abra o Grafana e navegue até **Connections** na barra lateral esquerda. **IoT Query** é executado em PostgreSQL, então você precisa adicionar uma fonte de dados PostgreSQL para permitir que o Grafana consulte seus dados de telemetria. {% endstep %} {% step %} #### Adicionar fonte de dados PostgreSQL O plug-in de fonte de dados PostgreSQL vem pré-instalado com o Grafana e oferece suporte nativo para conectar-se a bancos de dados PostgreSQL. Para adicionar a fonte de dados: 1. Na seção Connections, procure 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 Sua **IoT Query** os detalhes da 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 telemetria. Localize os parâmetros de conexão na sua conta Navixy e no **IoT Query** e-mail 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 **IoT Query** detalhes da conexão | | Porta | `Porta` | O 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 (chamado de "usuário do banco de dados" nos detalhes da 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 definiçõ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 funcionarão corretamente sem modificações. Você pode ajustar essas configurações mais tarde com base nos requisitos de segurança da sua organização, nas restrições de infraestrutura ou nas necessidades específicas do equipamento. Deixe todos os outros campos com seus valores padrão na configuração inicial. Você não precisa ativar nenhuma opção ou alternância adicional. {% 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 consiga se comunicar com sucesso com seu **IoT Query** da sua organização. Para verificar e salvar: 1. Dê um nome descritivo à sua conexão (por exemplo, "**IoT Query** Produção" ou "Análise de Frota") 2. Clique **Salvar e testar** para verificar sua conexão 3. Uma mensagem verde de sucesso indica que a conexão está funcionando corretamente {% endstep %} {% endstepper %} ## Criando sua primeira visualização Criar sua primeira visualização ajuda você a entender como o Grafana consulta **IoT Query** e exibe dados de telemetria. Esse processo envolve criar um dashboard, adicionar um painel, configurar uma consulta e selecionar um formato de visualização apropriado. {% stepper %} {% step %} **Criar um novo dashboard** Os dashboards no Grafana servem como contêineres para várias visualizações. Criar um dashboard dedicado ajuda você 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 oferece dois modos de consulta: um Builder visual e um editor de Código. Para **IoT Query** conexões, o editor de Código oferece controle total sobre consultas SQL e é recomendado para análise de dados de telemetria. Para escrever sua consulta: 1. No editor de consultas, altere de **Builder** para **Código** modo 2. Insira sua consulta SQL diretamente Exemplo de consulta 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 [Recipe Book de SQL](https://www.navixy.com/docs/analytics/example-queries). {% endstep %} {% step %} **Definir formato de visualização** O formato de visualização determina como seus dados aparecem no dashboard. Diferentes formatos são adequados para 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: 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érie temporal** ou o formato de sua preferência 4. Observe a exibição dos dados para garantir que apareçam 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 alterações automaticamente, então você pode perder seu trabalho se navegar para outra página sem salvar. Para salvar uma visualização: 1. Clique **Salvar** 2. Forneça um nome descritivo para o 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 As 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, nas suas consultas, as variáveis permitem que os usuários selecionem diferentes valores em menus suspensos sem editar o SQL subjacente. Isso torna os dashboards mais flexíveis e fáceis de usar. {% stepper %} {% step %} **Acessar as 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 dele. 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** do dashboard (ícone de engrenagem) no canto superior direito 3. Navegue até a seção **Variáveis** 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 possíveis valores que os usuários podem selecionar. Os valores da variável são preenchidos dinamicamente por meio de consultas ao seu **IoT Query** da sua organização. 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**: Igual ao nome para consistência; isto é o que os usuários veem no dashboard 3. **Tipo**: Selecionar **Consulta** para preencher valores do banco de dados 2. **Opções de consulta:** 1. **Fonte de dados**: Selecione seu PostgreSQL **IoT Query** conexão no menu suspenso 2. **Consulta**: Insira uma consulta SQL para preencher os valores da variável Exemplo de consulta 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 ``` Depois de inserir a consulta, o Grafana a executa imediatamente e exibe uma prévia 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 as consultas de visualização para referenciá-la. As variáveis usam uma sintaxe especial com um 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 pela 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 texto em SQL. {% endstep %} {% step %} **Salvar e testar** Testar a variável garante que ela funcione corretamente e atualize as visualizações conforme o esperado. Certifique-se de salvar seu trabalho em cada etapa para evitar perder as alterações de configuração. Para concluir 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. Retorne à 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 (os nomes das variáveis diferenciam maiúsculas de minúsculas). {% endstep %} {% endstepper %} ### Importando dashboards prontos Dashboards prontos oferecem 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 de visualização, layout e otimização de consultas. No entanto, eles exigem configuração para se conectar ao seu específico **IoT Query** da sua organização. {% stepper %} {% step %} **Acesse 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 será exibida {% endstep %} {% step %} **Importar o dashboard** O processo de importação aceita configurações de dashboard em vários formatos, oferecendo flexibilidade na forma como você carrega dashboards prontos. 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 **Fazer upload do arquivo JSON** 2. Selecione o arquivo do dashboard 3. Forneça um nome e selecione a pasta de destino 4. Clique **Importar** Aguarde o término do upload do modelo de dashboard. Quando concluído, o dashboard aparecerá, mas ainda não exibirá dados porque ele continua conectado à fonte de dados original usada quando o modelo foi criado. {% endstep %} {% step %} **Atualizar conexões da fonte de dados** Esta é uma etapa crítica. Dashboards importados são inicialmente conectados a fontes de dados externas que não têm acesso aos seus **IoT Query** dados. Você deve atualizar cada visualização para usar sua PostgreSQL **IoT Query** conexão. Para atualizar as visualizações: 1. Abra o dashboard importado 2. Clique **Edite** o primeiro painel de visualização (procure o ícone de edição ou o menu de três pontos) 3. No editor de consultas, localize o seletor de fonte de dados 4. Altere a fonte de dados da fonte original do modelo para sua PostgreSQL **IoT Query** conexão 5. Clique **Executar consulta** para verificar se a visualização recupera dados com sucesso 6. Clique **Salvar** para preservar as alterações 7. Repita este processo para cada painel de visualização no dashboard {% hint style="info" %} Salve seu trabalho com frequência durante esse processo. Você pode ter várias visualizações para atualizar, e salvar após cada uma garante que você não perca o progresso. {% endhint %} {% endstep %} {% step %} **Atualizar variáveis do dashboard** Muitos dashboards prontos usam variáveis para filtragem e interatividade. Essas variáveis também estão conectadas à fonte de dados original e precisam ser atualizadas para consultar sua **IoT Query** da sua organização. Para atualizar as variáveis: 1. Abra **ícone de Configurações** → **Variáveis** 2. Você verá uma lista de todas as variáveis usadas no dashboard 3. Clique **Edite** na primeira variável 4. Localize o **Fonte de dados** menu suspenso na seção Opções de consulta 5. Altere-o para sua PostgreSQL **IoT Query** conexão 6. Verifique se a prévia 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 da lista Depois de atualizar todas as variáveis, salve o dashboard novamente. As variáveis agora devem ser preenchidas com valores do seu **IoT Query** da sua organização. {% endstep %} {% step %} **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: 1. Salve o dashboard uma última vez usando **Ctrl+S** ou o **Salvar** botão 2. Atualize completamente a página do navegador (ou use **F5**) 3. Verifique se todas as visualizações exibem os dados corretamente 4. Teste cada menu suspenso de variável para garantir que ele seja preenchido com valores 5. Selecione diferentes valores de variável e confirme que as visualizações sejam atualizadas de acordo 6. Experimente diferentes intervalos de tempo usando o seletor de tempo Se alguma visualização permanecer vazia ou apresentar erros, volte 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 **IoT Query** detalhes. 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 com o host e a porta especificados. Entre em contato com o administrador de rede se as tentativas de conexão forem bloqueadas. **Erro 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 conferindo o inspetor de consultas (clique no botão "Query inspector" no editor do painel). Certifique-se de que o intervalo de tempo selecionado inclua períodos em que existam dados no seu banco de dados. Confirme se a fonte de dados foi selecionada e conectada corretamente. Verifique se os nomes das tabelas e colunas na sua consulta correspondem à estrutura real do esquema. **Variável não funciona**: Verifique se a consulta da variável retorna valores conferindo a prévia na página de configuração da variável. Certifique-se de 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 e aplicada corretamente ao dashboard. Se o menu suspenso da variável estiver vazio, revise a consulta SQL da variável em busca de erros. **Desempenho lento da consulta**: Considere adicionar índices de banco de dados nas colunas consultadas com frequência, 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 [Recipe Book de SQL](https://www.navixy.com/docs/analytics/example-queries) 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. Painéis de séries temporais exigem uma coluna com o alias `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 da fonte 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 esquemas (`raw_business_data` ou `raw_telematics_data`) especificados nas consultas estão corretos para sua **IoT Query** instância. Certifique-se de que os nomes das tabelas e colunas correspondam à estrutura real do seu banco de dados. **O dashboard mostra erros**: Abra o editor de consultas de cada painel e clique em "Query inspector" para ver mensagens de erro detalhadas. Analise as mensagens de erro com atenção — elas frequentemente indicam problemas específicos, como colunas ausentes, tipos de dados incorretos ou erros de sintaxe. Certifique-se de que os nomes dos campos nas consultas correspondam exatamente ao seu **IoT Query** esquema (os nomes dos 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 são preenchidas**: Verifique se você atualizou a fonte de dados de cada variável, e não apenas os painéis de visualização. Confirme se 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" e não como "Custom" ou outros tipos. ## Próximos passos Depois de conectar com sucesso o Grafana à sua **IoT Query** instância: * Explore os schemas de dados disponíveis revisando a seção [Visão geral do esquema](/docs/analytics/pt-br/iot-query/schema-overview.md) para entender a estrutura dos dados, as relações entre as tabelas e os campos disponíveis. * Comece com consultas simples focadas em entidades de negócios específicas antes de criar dashboards complexos; isso ajuda você a aprender a estrutura dos dados e evitar problemas de desempenho. * Revise o [Recipe Book de SQL](/docs/analytics/pt-br/example-queries.md) para padrões de consulta comprovados e técnicas de otimização, além de exemplos de cenários comuns de análise de telemetria * Experimente diferentes tipos de visualização (séries temporais, tabelas, gauges, painéis de estatísticas) para encontrar a melhor representação para seus dados e casos de uso específicos * Considere criar vários dashboards para diferentes finalidades: monitoramento em tempo real, análise histórica, resumos executivos e relatórios operacionais. ### Suporte Para dúvidas técnicas ou assistência com **IoT Query** conexões, entre em contato com o suporte em . --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://navixy.com/docs/analytics/pt-br/iot-query/connection-setup/selecting-bi-tools/connecting-grafana.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.