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

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

Это руководство является частью комплекта документации DataHub и конкретно охватывает подключение Power BI к вашему хранилищу данных. Если вы все еще выбираете, какой инструмент BI использовать, обратитесь к Выбор инструментов BI обзор.

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

Английский

Обзор и учебное руководство по настройке DataHub + Grafana.

Español

Функции панели

• Визуализация данных датчиков в реальном времени

• Анализ временных рядов с настраиваемыми временными диапазонами

• Динамическая фильтрация с использованием переменных

• Поддержка нескольких источников данных

• Интерактивные графики и диаграммы

• Создание кастомных запросов с помощью SQL

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

• Grafana версии 9.3 или новее

• Плагин источника данных PostgreSQL (включен по умолчанию)

• Доступ в интернет для подключения к базе данных

• Активный экземпляр DataHub с учетными данными для подключения

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

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

1

Установите Grafana

1. Скачайте и установите Grafana с официального сайта: https://grafana.com/grafana/download

2. Следуйте инструкциям по установке для вашей операционной системы.

2

Загрузите шаблоны панелей (опционально)

Готовые шаблоны панелей доступны, чтобы помочь вам быстро начать работу без создания визуализаций с нуля. Эти шаблоны поддерживаются в репозитории bi-intergrations в папке grafana. Вы можете клонировать репозиторий, чтобы получить доступ к готовым панелям:

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

Проверьте папке grafana. папку на предмет доступных JSON-файлов панелей.

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

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

1

Доступ к вкладке Connections

Откройте Grafana и перейдите в Connections в левой боковой панели. DataHub работает на PostgreSQL, поэтому вам необходимо добавить источник данных PostgreSQL, чтобы Grafana могла выполнять запросы к вашим телематическим данным.

2

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

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

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

1. В разделе Connections найдите PostgreSQL

2. Нажмите Add new data source

3. Откроется страница конфигурации PostgreSQL

3

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

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

Найдите параметры подключения в вашей учетной записи Navixy и в приветственном письме DataHub.

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

Параметр	Поле конфигурации	Описание
Host	Host	Адрес серверa базы данных, указанный в ваших деталях подключения DataHub
Port	Port	По умолчанию 5432 для PostgreSQL
Database name	Database	Название назначенной вам базы данных
Username	User	Имя пользователя базы данных (в деталях подключения обозначено как "database user")
Password	Password	Ваш безопасный пароль от базы данных
SSL mode	SSL Mode	Установите в require для защищенных подключений
Версия PostgreSQL	Version	Выберите 9.3 (рекомендуемая настройка)

4

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

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

Оставьте все остальные поля со значениями по умолчанию для первоначальной настройки. Не нужно включать дополнительные переключатели или тумблеры.

5

Проверка соединения

Тестирование соединения перед сохранением гарантирует, что все параметры верны и Grafana может успешно связаться с вашим экземпляром DataHub.

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

1. Дайте вашему подключению описательный идентификатор (например, «DataHub Production» или «Fleet Analytics»)

2. Нажмите Save & Test чтобы проверить ваше подключение

3. Зеленое сообщение об успехе указывает, что соединение работает корректно

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

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

1

Создайте новую панель

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

Чтобы создать панель:

1. Перейдите в Dashboards в левой боковой панели

2. Нажмите Create Dashboard

3. Выберите Добавить визуализацию

4. Выберите источник данных PostgreSQL, который вы только что настроили

2

Настройте запрос

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

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

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

2. Введите ваш 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.

3

Установите формат визуализации

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

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

1. Нажмите Запустите запрос чтобы убедиться, что ваш запрос возвращает данные

2. Найдите селектор типа визуализации (обычно в правом верхнем углу панели)

3. Измените формат с Table на на Time series или на предпочитаемый вами формат

4. Просмотрите отображение данных, чтобы убедиться, что оно отображается корректно

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

4

Сохраните вашу визуализацию

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

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

1. Нажмите Save

2. Укажите описательное имя для вашей панели

3. Выберите или создайте папку для организации

4. Подтвердите операцию сохранения

Панель теперь доступна в вашем экземпляре Grafana и может быть доступна через меню Dashboards.

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

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

1

Доступ к настройкам переменных

Переменные настраиваются на уровне панели и применяются ко всем визуализациям внутри этой панели. Для создания и управления переменными нужно открыть настройки панели.

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

1. Откройте вашу панель

2. Нажмите на значок Settings (значок шестеренки) в правом верхнем углу

3. Перейдите в раздел Variables в левой панели

4. Раздел будет пуст, если переменные еще не созданы

2

Настройка переменной

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

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

1. Нажмите Add variable

2. Настройте следующие параметры:

   1. Общие настройки:

      1. Name: sensor_name (используйте четкий, описательный идентификатор без пробелов)

      2. Label: Совпадает с именем для согласованности, это то, что видят пользователи на панели

      3. Type: Выберите Query чтобы заполнять значения из базы данных

   2. Параметры запроса:

      1. Data source: Выберите ваше подключение PostgreSQL DataHub из выпадающего списка

      2. Query: Введите SQL-запрос для заполнения значений переменной

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

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

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

3

Применение переменных в запросах

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

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

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

2. Отредактируйте запрос

3. Замените захардкоженное значение ссылкой на переменную

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

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.

4

Сохраните и протестируйте

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

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

1. Нажмите Apply чтобы сохранить конфигурацию переменной

2. Нажмите Save dashboard чтобы сохранить все изменения

3. Вернитесь к основному виду панели

4. Найдите выпадающий список переменной в верхней части панели

5. Выберите разные имена датчиков из выпадающего списка

6. Наблюдайте, что визуализация автоматически обновляется данными для выбранного датчика

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

Импорт готовых панелей

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

1

Доступ к функции импорта

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

1. Перейдите в Dashboards

2. Нажмите New → Import

3. Появится окно загрузки

2

Импорт панели

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

Вы можете импортировать панели, используя:

• Идентификатор панели с Grafana.com

• JSON-файл скачанный из репозитория bi-intergrations

• JSON-модель вставленная напрямую

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

1. Нажмите Загрузите JSON-файл

2. Выберите файл панели

3. Укажите имя и выберите папку назначения

4. Нажмите Import

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

3

Обновите подключения источников данных

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

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

1. Откройте импортированную панель

2. Нажмите Edit в первой панели визуализации (ищите значок редактирования или меню из трех точек)

3. В редакторе запросов найдите селектор источника данных

4. Измените источник данных с оригинального источника шаблона на ваше подключение PostgreSQL DataHub

5. Нажмите Запустите запрос чтобы убедиться, что визуализация успешно получает данные

6. Нажмите Save чтобы сохранить изменения

7. Повторите этот процесс для каждой панели визуализации на панели

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

4

Обновление переменных панели

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

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

1. Откройте Settings → Variables

2. Вы увидите список всех переменных, используемых на панели

3. Нажмите Edit на первой переменной

4. Найдите Data source выпадающий список в разделе параметров запроса

5. Измените его на ваше подключение PostgreSQL DataHub

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

7. Нажмите Apply чтобы подтвердить изменения

8. Повторите для каждой переменной в списке

После обновления всех переменных снова сохраните панель. Переменные теперь должны заполняться значениями из вашего экземпляра DataHub.

5

Проверьте работоспособность панели

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

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

1. Сохраните панель в последний раз, используя Ctrl+S или кнопку Save button

2. Полностью обновите страницу браузера (или используйте F5)

3. Убедитесь, что все визуализации отображают данные корректно

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

5. Выберите разные значения переменных и подтвердите, что визуализации соответствующим образом обновляются

6. Попробуйте разные временные диапазоны с помощью селектора времени

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

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

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

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

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

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

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

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

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

Медленная производительность запросов: Рассмотрите возможность добавления индексов в базе данных для часто запрашиваемых столбцов, таких как device_time и device_id. Ограничьте временные диапазоны, используя фильтры времени более строго. Оптимизируйте структуру запросов, выбирая только необходимые столбцы вместо использования SELECT *. Обратитесь к SQL Recipe Book для примеров оптимизации производительности и проверенных шаблонов запросов.

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

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

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

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

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

Следующие шаги

После успешного подключения Grafana к вашему экземпляру DataHub:

• Изучите доступные схемы данных, просмотреть Обзор схемы чтобы понять структуру данных, взаимосвязи между таблицами и доступные поля.

• Начните с простых запросов, ориентированных на конкретные бизнес-объекты, прежде чем создавать сложные панели; это поможет вам изучить структуру данных и избежать проблем с производительностью.

• Просмотрите SQL Recipe Book для проверенных шаблонов запросов и методов оптимизации, а также примеров распространенных сценариев телематической аналитики

• Экспериментируйте с различными типами визуализаций (временные ряды, таблицы, индикаторы, stat-панели), чтобы найти наилучшее представление для ваших конкретных данных и случаев использования

• Рассмотрите возможность создания нескольких панелей для разных целей: мониторинг в реальном времени, исторический анализ, руководящие сводки и операционные отчеты.

Поддержка

По техническим вопросам или за помощью с подключениями DataHub обращайтесь в службу поддержки по адресу [email protected].