# Подключение Grafana

Это руководство показывает, как подключить Grafana к **IoT Query** для визуализации телематических данных и данных автопарка. Grafana предоставляет мощные возможности визуализации для мониторинга состояния транспортных средств, данных датчиков и других метрик в режиме реального времени.

{% hint style="info" %}
эта документация **IoT Query** и, в частности, описывает подключение Power BI к вашему хранилищу данных. Если вы всё ещё выбираете, какой BI-инструмент использовать, обратитесь к [Выбор BI-инструментов](https://www.navixy.com/docs/analytics/datahub/connection-setup/selecting-bi-tools) обзору.
{% endhint %}

Посмотрите краткий видеообзор, чтобы увидеть, что возможно с **IoT Query**+ комбинацией Grafana (доступно на английском и испанском языках):

{% tabs %}
{% tab title="English" %}
{% embed url="<https://youtu.be/jGO3hIAjPCo?si=7bzWO4XrTwGnTq3c>" %}
**IoT Query** + обзор Grafana и руководство по настройке.
{% endembed %}
{% endtab %}

{% tab title="Español" %}
{% embed url="<https://youtu.be/jEf7i_mAWPE?si=pru7QyYHzyoqK79Q>" %}
Обзор и руководство по настройке **IoT Query** + Grafana.
{% endembed %}
{% endtab %}
{% endtabs %}

## Функции дашборда

* Визуализация данных датчиков в реальном времени
* Анализ временных рядов с настраиваемыми диапазонами времени
* Динамическая фильтрация с использованием переменных
* Поддержка нескольких источников данных
* Интерактивные графики и диаграммы
* Построение пользовательских запросов с SQL

## Технические требования

* Grafana 9.3 или более поздняя версия
* Плагин источника данных PostgreSQL (входит по умолчанию)
* Доступ в Интернет для подключения к базе данных
* Активная **IoT Query** инстанция с учетными данными для подключения

## Установка и настройка

Grafana должна быть установлена в вашей системе, прежде чем вы сможете подключиться к **IoT Query**.

{% stepper %}
{% step %}

#### Установите Grafana

1. Скачайте и установите Grafana с официального сайта:\
   <https://grafana.com/grafana/download>
2. Следуйте инструкциям по установке для вашей операционной системы.
   {% endstep %}

{% step %}

#### Скачайте шаблоны дашбордов (необязательно)

Готовые шаблоны дашбордов доступны, чтобы помочь вам быстро начать работу без создания визуализаций с нуля. Эти шаблоны поддерживаются в [репозитории bi-intergrations](https://github.com/SquareGPS/bi-intergrations) в папке `grafana` . Вы можете клонировать репозиторий, чтобы получить доступ к готовым дашбордам:

```bash
git clone https://github.com/SquareGPS/bi-intergrations.git
```

Проверьте папку `grafana` для доступных JSON-файлов дашбордов.
{% endstep %}
{% endstepper %}

## Подключение к базе данных

Раздел Connections в Grafana — это место, где вы управляете всеми интеграциями источников данных.

{% stepper %}
{% step %}

#### Откройте вкладку Connections

Откройте Grafana и перейдите в **Connections** в левой боковой панели. **IoT Query** работает на PostgreSQL, поэтому вам нужно добавить источник данных PostgreSQL, чтобы Grafana могла выполнять запросы к вашим телематическим данным.
{% endstep %}

{% step %}

#### Добавьте источник данных PostgreSQL

Плагин источника данных PostgreSQL предустановлен вместе с Grafana и обеспечивает встроенную поддержку подключения к базам данных PostgreSQL.

Чтобы добавить источник данных:

1. В разделе Connections найдите **PostgreSQL**
2. Нажмите **Добавить новый источник данных**
3. Откроется страница конфигурации PostgreSQL
   {% endstep %}

{% step %}

#### Настройте параметры подключения

Ваш **IoT Query** данные подключения содержат всю информацию, необходимую для установления защищенного соединения. Эти параметры уникальны для вашей инстанции и гарантируют, что Grafana сможет получить доступ к вашим телематическим данным.

Найдите параметры подключения в вашей учетной записи Navixy и в **IoT Query** приветственном письм&#x435;**.**

**Справка по параметрам подключения**

| Параметр          | Поле конфигурации | Описание                                                                            |
| ----------------- | ----------------- | ----------------------------------------------------------------------------------- |
| Хост              | `Хост`            | Адрес сервера базы данных, указанный в ваших **IoT Query** данных подключения       |
| Порт              | `Порт`            | По умолчанию 5432 для PostgreSQL                                                    |
| Имя базы данных   | `База данных`     | Имя базы данных, назначенное вам                                                    |
| Имя пользователя  | `Пользователь`    | Ваше имя пользователя базы данных (в данных подключения называется "database user") |
| Пароль            | `Пароль`          | Ваш надежный пароль для базы данных                                                 |
| Режим SSL         | `Режим SSL`       | Установите значение `require` для защищенных соединений                             |
| Версия PostgreSQL | `Версия`          | Выберите **9.3** (рекомендуемая настройка)                                          |
| {% endstep %}     |                   |                                                                                     |

{% step %}

#### Настройте дополнительные параметры

Помимо основных параметров подключения, Grafana предлагает дополнительные параметры конфигурации. Для большинства пользователей значения по умолчанию подходят и будут работать корректно без изменений. Вы сможете настроить эти параметры позже в зависимости от требований безопасности вашей организации, ограничений инфраструктуры или специфических потребностей оборудования.

Оставьте все остальные поля со значениями по умолчанию для первоначальной настройки. Вам не нужно включать какие-либо дополнительные переключатели или тумблеры.
{% endstep %}

{% step %}

#### Проверьте соединение

Проверка соединения перед сохранением гарантирует, что все параметры указаны верно и что Grafana может успешно взаимодействовать с вашим **IoT Query** экземпляру вашей организации.

Чтобы проверить и сохранить:

1. Назовите ваше подключение описательным идентификатором (например, "**IoT Query** Production" или "Fleet Analytics")
2. Нажмите **Save & Test** чтобы проверить соединение
3. Зеленое сообщение об успешном выполнении означает, что соединение работает корректно
   {% endstep %}
   {% endstepper %}

## Создание вашей первой визуализации

Создание вашей первой визуализации помогает понять, как Grafana выполняет запросы **IoT Query** и отображает телематические данные. Этот процесс включает создание дашборда, добавление панели, настройку запроса и выбор подходящего формата визуализации.

{% stepper %}
{% step %}
**Создайте новую панель мониторинга**

Дашборды в Grafana служат контейнерами для нескольких визуализаций. Создание отдельного дашборда помогает организовать связанные визуализации и предоставляет центральное место для мониторинга определенных аспектов работы вашего автопарка.

Чтобы создать дашборд:

1. Перейдите в **Панели мониторинга** в левой боковой панели
2. Нажмите **Создать дашборд**
3. Выберите **Добавить визуализацию**
4. Выберите источник данных PostgreSQL, который вы только что настроили
   {% endstep %}

{% step %}
**Настройте запрос**

Grafana предоставляет два режима запросов: визуальный Builder и редактор Code. Для **IoT Query** подключений редактор Code дает полный контроль над SQL-запросами и рекомендуется для анализа телематических данных.

Чтобы написать запрос:

1. В редакторе запросов переключитесь с **Builder** на **Code** режим
2. Введите SQL-запрос напрямую

Пример запроса для визуализации данных датчика:

```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
```

Запрос включает компонент времени (`device_time AS time`), который необходим для визуализаций временных рядов. Функция `$__timeFilter()` — это макрос Grafana, который автоматически применяет выбранный в дашборде диапазон времени к вашему запросу.

Для получения дополнительных примеров запросов обратитесь к [SQL Recipe Book](https://www.navixy.com/docs/analytics/example-queries).
{% endstep %}

{% step %}
**Задайте формат визуализации**

Формат визуализации определяет, как ваши данные будут отображаться на дашборде. Разные форматы подходят для разных типов данных — временные ряды хорошо подходят для отображения показаний датчиков во времени, а таблицы лучше подходят для подробных записей.

Чтобы настроить формат:

1. Нажмите **Выполните запрос** чтобы убедиться, что запрос возвращает данные
2. Найдите селектор типа визуализации (обычно в правом верхнем углу панели)
3. Измените формат с **Таблица** на **Time series** или на предпочитаемый вами формат
4. Проверьте отображение данных, чтобы убедиться, что они показываются корректно

Визуализации временных рядов для корректной работы требуют столбец времени и числовые значения. Ваш запрос должен возвращать данные в формате, подходящем для выбранного типа визуализации.
{% endstep %}

{% step %}
**Сохраните вашу визуализацию**

Сохранение работы сохраняет конфигурацию визуализации и делает ее доступной для последующего использования. Регулярное сохранение важно — Grafana не сохраняет изменения автоматически, поэтому вы можете потерять свою работу, если перейдете на другую страницу без сохранения.

Чтобы сохранить визуализацию:

1. Нажмите **Сохраните**
2. Задайте описательное имя для вашего дашборда
3. Выберите или создайте папку для организации
4. Подтвердите операцию сохранения

Теперь дашборд доступен в вашей инстанции Grafana и его можно открыть через меню Dashboards.
{% endstep %}
{% endstepper %}

### Работа с переменными

Переменные — одна из самых мощных функций Grafana для создания динамических интерактивных дашбордов. Вместо жесткого указания конкретных значений, таких как имена датчиков или идентификаторы устройств, в ваших запросах, переменные позволяют пользователям выбирать разные значения из выпадающих списков без изменения базового SQL. Это делает дашборды более гибкими и удобными в использовании.

{% stepper %}
{% step %}
**Откройте настройки переменных**

Переменные настраиваются на уровне дашборда и применяются ко всем визуализациям внутри этого дашборда. Вам нужно открыть настройки дашборда, чтобы создавать и управлять переменными.

Чтобы начать:

1. Откройте ваш дашборд
2. Нажмите значок **Settings** дашборда (значок шестеренки) в правом верхнем углу
3. Перейдите в раздел **Variables** в левой панели
4. Этот раздел будет пустым, если переменные еще не созданы
   {% endstep %}

{% step %}
**Настройте переменную**

Для каждой переменной требуется имя, источник данных и запрос, который возвращает возможные значения, доступные пользователю для выбора. Значения переменных заполняются динамически путем выполнения запроса к вашему **IoT Query** экземпляру вашей организации.

Чтобы создать переменную:

1. Нажмите **Добавить переменную**
2. Настройте следующие параметры:
   1. **Общие настройки:**
      1. **Name**: `sensor_name` (используйте понятный, описательный идентификатор без пробелов)
      2. **Label**: То же, что и имя, для единообразия; именно это видят пользователи на дашборде
      3. **Type**: Выберите **Query** чтобы заполнять значения из базы данных
   2. **Параметры запроса:**
      1. **Источник данных**: Выберите ваш PostgreSQL **IoT Query** подключение в раскрывающемся списке
      2. **Query**: Введите SQL-запрос для заполнения значений переменной

Пример запроса для вывода всех датчиков определенного устройства:

```sql
SELECT DISTINCT sensor_name
FROM raw_telematics_data.inputs
WHERE device_id = 12345
ORDER BY sensor_name
```

После ввода запроса Grafana немедленно выполняет его и отображает предварительный просмотр возвращенных значений в нижней части страницы конфигурации. Это подтверждает, что ваш запрос работает корректно, и показывает, какие параметры будут доступны в раскрывающемся списке.
{% endstep %}

{% step %}
**Применение переменных в запросах**

После создания переменной вам нужно обновить запросы визуализации, чтобы ссылаться на нее. Переменные используют специальный синтаксис с префиксом знака доллара, и Grafana автоматически подставляет выбранное значение при выполнении запросов.

Чтобы использовать переменную:

1. Откройте визуализацию, которую хотите сделать динамической
2. Отредактируйте запрос
3. Замените жестко заданное значение ссылкой на переменную

Пример обновленного запроса с использованием переменной:

```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
```

Обратите внимание, как `'temperature'` было заменено на `'$sensor_name'`. Кавычки важны для строковых значений в SQL.
{% endstep %}

{% step %}
**Сохраните и проверьте**

Проверка переменной гарантирует, что она работает корректно и обновляет визуализации ожидаемым образом. Убедитесь, что сохраняете работу на каждом этапе, чтобы не потерять изменения конфигурации.

Чтобы завершить настройку:

1. Нажмите **Применить** чтобы сохранить конфигурацию переменной
2. Нажмите **Сохранить дашборд** чтобы сохранить все изменения
3. Вернитесь к основному виду дашборда
4. Найдите выпадающий список переменной в верхней части дашборда
5. Выберите разные имена датчиков в раскрывающемся списке
6. Проверьте, что визуализация автоматически обновляется данными для выбранного датчика

Если визуализация не обновляется при изменении выбора переменной, убедитесь, что имя переменной в вашем запросе в точности совпадает с именем созданной переменной (имена переменных чувствительны к регистру).
{% endstep %}
{% endstepper %}

### Импорт готовых дашбордов

Готовые дашборды — это быстрый способ начать визуализацию данных без создания всего с нуля. Эти дашборды разработаны опытными пользователями и включают лучшие практики для визуализации, компоновки и оптимизации запросов. Однако для подключения к вашей конкретной **IoT Query** экземпляру вашей организации.

{% stepper %}
{% step %}
**Откройте функцию импорта**

Функция импорта Grafana позволяет загружать конфигурации дашбордов из JSON-файлов или напрямую с Grafana.com, используя идентификаторы дашбордов.

1. Перейдите в **Панели мониторинга**
2. Нажмите **New** → **Чтобы загрузить ранее сохранённый рабочий процесс, используйте функцию**
3. Появится окно загрузки
   {% endstep %}

{% step %}
**Импортируйте дашборд**

Процесс импорта поддерживает конфигурации дашбордов в нескольких форматах, что дает вам гибкость при загрузке готовых дашбордов.

Вы можете импортировать дашборды с помощью:

* **Идентификатор дашборда** с Grafana.com
* **JSON-файл** скачанный из репозитория bi-intergrations
* **JSON-модель** вставленная напрямую

Если используется JSON-файл:

1. Нажмите **Загрузить JSON-файл**
2. Выберите файл дашборда
3. Укажите имя и выберите папку назначения
4. Нажмите **Чтобы загрузить ранее сохранённый рабочий процесс, используйте функцию**

Дождитесь завершения загрузки шаблона дашборда. После завершения дашборд появится, но пока не будет отображать данные, потому что он по-прежнему подключен к исходному источнику данных, который использовался при создании шаблона.
{% endstep %}

{% step %}
**Обновите подключения к источнику данных**

Это критически важный шаг. Импортированные дашборды изначально подключены к внешним источникам данных, которые не имеют доступа к вашим **IoT Query** данным. Вам нужно обновить каждую визуализацию, чтобы она использовала ваше PostgreSQL **IoT Query** подключение.

Чтобы обновить визуализации:

1. Откройте импортированный дашборд
2. Нажмите **Edit** на первой панели визуализации (найдите значок редактирования или меню с тремя точками)
3. В редакторе запросов найдите селектор источника данных
4. Измените источник данных с исходного источника шаблона на ваше PostgreSQL **IoT Query** подключение
5. Нажмите **Выполните запрос** чтобы убедиться, что визуализация успешно получает данные
6. Нажмите **Сохраните** чтобы сохранить изменения
7. Повторите этот процесс для каждой панели визуализации на дашборде

{% hint style="info" %}
Регулярно сохраняйте работу в ходе этого процесса. У вас может быть несколько визуализаций для обновления, и сохранение после каждой из них гарантирует, что вы не потеряете прогресс.
{% endhint %}
{% endstep %}

{% step %}
**Обновите переменные дашборда**

Многие готовые дашборды используют переменные для фильтрации и интерактивности. Эти переменные также подключены к исходному источнику данных и должны быть обновлены для выполнения запросов к вашему **IoT Query** экземпляру вашей организации.

Чтобы обновить переменные:

1. Откройте **Settings** → **Variables**
2. Вы увидите список всех переменных, используемых в дашборде
3. Нажмите **Edit** на первой переменной
4. Найдите **Источник данных** выпадающий список в разделе Query options
5. Измените его на ваш PostgreSQL **IoT Query** подключение
6. Убедитесь, что предварительный просмотр внизу показывает ожидаемые значения из вашей базы данных
7. Нажмите **Применить** чтобы подтвердить изменения
8. Повторите для каждой переменной в списке

После обновления всех переменных снова сохраните дашборд. Теперь переменные должны заполняться значениями из вашего **IoT Query** экземпляру вашей организации.
{% endstep %}

{% step %}
**Проверьте работу дашборда**

После того как вы обновили все визуализации и переменные, убедитесь, что все работает корректно в комплексе. Эта финальная проверка гарантирует, что дашборд полностью функционален и готов к регулярному использованию.

Чтобы проверить:

1. Сохраните дашборд в последний раз, используя **Ctrl+S** или **Сохраните** кнопку
2. Полностью обновите страницу браузера (или используйте **F5**)
3. Проверьте, что все визуализации корректно отображают данные
4. Проверьте каждый выпадающий список переменной, чтобы убедиться, что он заполняется значениями
5. Выберите разные значения переменных и подтвердите, что визуализации обновляются соответствующим образом
6. Попробуйте разные диапазоны времени с помощью выбора времени

Если какие-либо визуализации остаются пустыми или показывают ошибки, вернитесь в режим редактирования и проверьте источник данных и конфигурацию запроса для этих конкретных панелей.
{% endstep %}
{% endstepper %}

## Устранение неполадок

### Проблемы с подключением к базе данных

**Ошибка подключения**: Убедитесь, что учетные данные и параметры подключения точно соответствуют вашим **IoT Query** данным. Проверьте, что хост, порт, имя базы данных, имя пользователя и пароль указаны верно.

**Ошибка брандмауэра**: Убедитесь, что ваша сеть разрешает соединения с указанным хостом и портом. Обратитесь к сетевому администратору, если попытки подключения блокируются.

**Ошибка SSL/TLS**: Убедитесь, что режим SSL установлен на `require` и что ваша инстанция Grafana поддерживает SSL-соединения.

### Проблемы с запросами и визуализацией

**Пустая визуализация**: Сначала убедитесь, что запрос действительно возвращает данные, проверив инспектор запросов (нажмите кнопку "Query inspector" в редакторе панели). Убедитесь, что выбранный диапазон времени включает периоды, когда данные есть в вашей базе данных. Подтвердите, что источник данных выбран и подключен правильно. Проверьте, что имена таблиц и столбцов в вашем запросе соответствуют фактической структуре схемы.

**Переменная не работает**: Убедитесь, что запрос переменной возвращает значения, проверив предварительный просмотр на странице конфигурации переменной. Убедитесь, что ссылка на переменную в вашем запросе использует правильный синтаксис (`$variable_name`) без опечаток. Проверьте, что переменная правильно сохранена и применена к дашборду. Если раскрывающийся список переменной пуст, проверьте SQL-запрос переменной на наличие ошибок.

**Медленная производительность запросов**: Рассмотрите возможность добавления индексов базы данных для часто запрашиваемых столбцов, таких как `device_time` : Изучите исходные схемы ( `device_id`. Ограничьте диапазоны данных, более строго используя фильтры по времени. Оптимизируйте структуру запроса, выбирая только необходимые столбцы вместо `SELECT *`. Обратитесь к [SQL Recipe Book](https://www.navixy.com/docs/analytics/example-queries) за примерами оптимизации производительности и проверенными шаблонами запросов.

**Несоответствие формата**: Убедитесь, что ваш запрос возвращает данные в формате, ожидаемом вашим типом визуализации. Панели временных рядов требуют столбец, алиасированный как `time` и числовые столбцы значений. Панели таблиц принимают любую структуру столбцов. Графические панели требуют временные и числовые данные. Ознакомьтесь с документацией Grafana для получения конкретных требований к каждому типу визуализации.

### Проблемы с импортом

**Отсутствуют данные после импорта**: Убедитесь, что подключения к источникам данных обновлены для всех панелей и переменных. Не пропускайте ни одну панель в процессе обновления. Проверьте, что имена схем (`raw_business_data` или `raw_telematics_data`) указанные в запросах, корректны для вашей **IoT Query** инстанции. Убедитесь, что имена таблиц и столбцов соответствуют фактической структуре вашей базы данных.

**На дашборде отображаются ошибки**: Откройте редактор запросов каждой панели и нажмите "Query inspector", чтобы увидеть подробные сообщения об ошибках. Внимательно изучите сообщения об ошибках — они часто указывают на конкретные проблемы, такие как отсутствующие столбцы, неверные типы данных или синтаксические ошибки. Убедитесь, что имена полей в запросах соответствуют вашей **IoT Query** схеме в точности (имена полей чувствительны к регистру). Проверьте, что типы данных, возвращаемые запросами, совместимы с типом визуализации.

**Переменные не заполняются**: Проверьте, что вы обновили источник данных для каждой переменной, а не только для панелей визуализации. Убедитесь, что запросы переменных синтаксически корректны и возвращают данные при прямом выполнении. Убедитесь, что тип переменной установлен в "Query", а не в "Custom" или другой тип.

## Обработка потоковых данных не поддерживается.

После успешного подключения Grafana к вашей **IoT Query** инстанции:

* Изучить доступные схемы данных, просмотрев раздел [Обзор схемы](/docs/analytics/ru/iot-query/schema-overview.md) чтобы понять структуру данных, связи между таблицами и доступные поля.
* Начинайте с простых запросов, ориентированных на конкретные бизнес-сущности, прежде чем строить сложные дашборды; это помогает вам понять структуру данных и избежать проблем с производительностью.
* Ознакомьтесь с [SQL Recipe Book](/docs/analytics/ru/example-queries.md) для проверенных шаблонов запросов и техник оптимизации, а также примеров распространенных сценариев аналитики телематических данных
* Экспериментируйте с разными типами визуализаций (временные ряды, таблицы, индикаторы, стат-панели), чтобы найти наилучшее представление для ваших конкретных данных и сценариев использования.
* Рассмотрите возможность создания нескольких дашбордов для разных целей: мониторинг в реальном времени, исторический анализ, сводки для руководства и операционные отчеты.

### Поддержка

По техническим вопросам или за помощью с **IoT Query** подключениями обращайтесь в службу поддержки по адресу <support@navixy.com>.


---

# 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/ru/iot-query/connection-setup/selecting-bi-tools/connecting-grafana.md?ask=<question>
```

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.