Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Источники данныхbreadcrumb arrow MySQLbreadcrumb arrow Устранение неполадок
Последнее обновление: августа 10, 2026

Устранение неполадок источника данных MySQL

В этом документе приведены решения распространённых проблем, с которыми вы можете столкнуться при настройке или использовании источника данных MySQL в Grafana.

Ошибки подключения

Эти ошибки возникают, когда Grafana не может установить или поддерживать соединение с сервером MySQL.

Не удаётся подключиться к серверу

Сообщение об ошибке: “dial tcp: connection refused” или “Could not connect to MySQL”

Причина: Grafana не может установить сетевое соединение с сервером MySQL.

Решение:

  1. Убедитесь, что сервер MySQL запущен и доступен.
  2. Проверьте, что хост и порт указаны верно в конфигурации источника данных. Порт MySQL по умолчанию — 3306.
  3. Убедитесь, что нет правил межсетевого экрана, блокирующих соединение между Grafana и MySQL.
  4. Проверьте, что MySQL настроен на разрешение удалённых подключений, посмотрев параметр bind-address в вашей конфигурации MySQL.
  5. Для Grafana Cloud убедитесь, что вы настроили Private data source connect, если ваш экземпляр MySQL не доступен публично.

Тайм-аут соединения

Сообщение об ошибке: “Connection timed out” или “I/O timeout”

Причина: Соединение с MySQL истекло по тайм-ауту до получения ответа.

Решение:

  1. Проверьте сетевую задержку между Grafana и MySQL.
  2. Убедитесь, что MySQL не перегружен и не испытывает проблем с производительностью.
  3. Проверьте, не разрывают ли соединение по тайм-ауту какие-либо сетевые устройства (балансировщики нагрузки, прокси).
  4. Увеличьте параметр wait_timeout в MySQL, если соединения обрываются по тайм-ауту в периоды простоя.

Сбои соединения TLS/SSL

Ошибки TLS возникают, когда сервер MySQL требует или ожидает зашифрованные соединения, а источник данных Grafana настроен на несоответствующий режим. Типичные сообщения об ошибках:

  • “TLS handshake failed” или “x509: certificate verify failed”
  • “Connection refused” или соединение сбрасывается немедленно
  • “Error 3159: Connections using insecure transport are prohibited while –require_secure_transport=ON”

Возможные причины и решения:

Причина Решение
В MySQL включён require_secure_transport, или AWS RDS Proxy требует TLS Включите With CA Cert или Skip TLS Verification в конфигурации источника данных. Любой из вариантов устанавливает TLS-соединение.
Самоподписанный или частный CA-сертификат не является доверенным Включите With CA Cert и укажите корневой сертификат в поле TLS/SSL Root Certificate.
Сертификат истёк или не соответствует имени хоста Обновите сертификат или включите Skip TLS Verification только для сред разработки.
Сбой TLS-рукопожатия при подключении к AWS RDS или RDS Proxy Укажите корневой CA-сертификат Amazon RDS в поле TLS/SSL Root Certificate при включённом With CA Cert.
Организация требует взаимного TLS (mTLS) Включите Use TLS Client Auth и укажите как клиентский сертификат, так и ключ в дополнение к CA-сертификату.

Note

Skip TLS Verification и With CA Cert оба устанавливают зашифрованные соединения. Use TLS Client Auth не нужен, если ваша конфигурация не требует взаимного TLS. Для большинства подключений к AWS RDS и RDS Proxy достаточно With CA Cert с корневым CA Amazon.

Для провижиненных источников данных включите TLS в jsonData:

YAML 
jsonData:
  tlsAuthWithCACert: true
secureJsonData:
  tlsCACert: ${CA_CERT}

Чтобы вместо этого пропустить проверку сертификата, используйте:

YAML 
jsonData:
  tlsSkipVerify: true

Все доступные параметры провижининга TLS см. в разделе TLS provisioning examples.

Соединение сброшено удалённой стороной

Сообщение об ошибке: “Connection reset by peer” или “EOF”

Причина: Сервер MySQL неожиданно закрыл соединение.

Решение:

  1. Проверьте параметр max_connections на сервере MySQL, чтобы убедиться, что он не превышается.
  2. Убедитесь, что параметры wait_timeout и interactive_timeout в MySQL не заданы слишком низко.
  3. Увеличьте параметр Max lifetime в конфигурации источника данных Grafana, чтобы он был ниже, чем wait_timeout в MySQL.
  4. Проверьте журналы сервера MySQL на наличие ошибок или сообщений, связанных с соединениями.

Ошибки аутентификации

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

Доступ запрещён для пользователя

Сообщение об ошибке: “Access denied for user ‘username’@‘host’” или “Authentication failed”

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

Решение:

  1. Убедитесь, что имя пользователя и пароль верны.

  2. Проверьте, что пользователь существует в MySQL и включён.

  3. Убедитесь, что у пользователя есть разрешение подключаться с IP-адреса сервера Grafana. MySQL ограничивает доступ в зависимости от подключающегося хоста:

    SQL 
    SELECT user, host FROM mysql.user WHERE user = 'your_user';

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

    SQL 
    CREATE USER 'grafana'@'grafana_server_ip' IDENTIFIED BY 'password';

  5. Если используется плагин аутентификации mysql_native_password, убедитесь, что он включён на сервере.

Нет доступа к базе данных

Сообщение об ошибке: “Access denied for user ‘username’@‘host’ to database ‘dbname’”

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

Решение:

  1. Убедитесь, что имя базы данных указано верно в конфигурации источника данных.

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

    SQL 
    GRANT SELECT ON your_database.* TO 'grafana'@'grafana_server_ip';
FLUSH PRIVILEGES;

  3. Для продуктивных сред предоставляйте разрешения только на конкретные таблицы:

    SQL 
    GRANT SELECT ON your_database.your_table TO 'grafana'@'grafana_server_ip';

Проблемы с аутентификацией PAM

Сообщение об ошибке: “Authentication plugin ‘auth_pam’ cannot be loaded” или ошибки пароля в открытом виде

Причина: Аутентификация PAM (Pluggable Authentication Modules) требует передачи пароля в открытом виде.

Решение:

  1. Включите Allow Cleartext Passwords в конфигурации источника данных, если используется аутентификация PAM.
  2. Убедитесь, что TLS включён для защиты передачи пароля при использовании паролей в открытом виде.
  3. Проверьте, что плагин PAM корректно установлен и настроен на сервере MySQL.

Ошибки запросов

Эти ошибки возникают при проблемах с синтаксисом или конфигурацией запросов.

Столбец времени не найден или некорректен

Сообщение об ошибке: “Could not find time column” или визуализация временных рядов не отображает данные

Причина: Запрос не возвращает корректно отформатированный столбец time для визуализации временных рядов.

Решение:

  1. Убедитесь, что ваш запрос включает столбец с именем time при использовании формата Time series.
  2. Используйте макрос $__time() для преобразования столбца даты: $__time(your_date_column).
  3. Проверьте, что столбец времени имеет допустимый тип даты/времени MySQL (DATETIME, TIMESTAMP, DATE) или содержит значения Unix epoch.
  4. Убедитесь, что результирующий набор отсортирован по столбцу времени с помощью ORDER BY.

Ошибки раскрытия макросов

Сообщение об ошибке: “Error parsing query” или макросы отображаются в запросе нераскрытыми

Причина: Макросы Grafana используются неправильно.

Решение:

  1. Проверьте синтаксис макроса: используйте $__timeFilter(column), а не $_timeFilter(column).
  2. Проверьте, что имя столбца, передаваемое в макросы, существует в вашей таблице.
  3. Просмотрите раскрытый запрос, нажав Generated SQL после выполнения запроса, чтобы отладить раскрытие макросов.
  4. Убедитесь, что для зарезервированных слов или специальных символов в именах столбцов используются обратные кавычки: $__timeFilter(\time-column`)`.

Символ # в строках в кавычках вызывает ошибки запросов

Сообщение об ошибке: Запрос возвращает неожиданные результаты или ошибки, когда строковые значения содержат #

Причина: В версиях до Grafana 13.0 логика удаления комментариев SQL ошибочно воспринимала # внутри строк в кавычках (например, WHERE color = '#FF0000') как разделитель комментария, что удаляло остаток строки.

Решение:

  1. Обновитесь до Grafana 13.0 или более поздней версии, где # внутри строк в кавычках сохраняется.
  2. Как обходной путь в старых версиях используйте функцию CONCAT или шестнадцатеричный литерал, чтобы избежать символа # в строковых литералах.

Проблемы с часовым поясом и смещением времени

Причина: Данные временных рядов выглядят смещёнными или не совпадают с ожидаемым временем.

Решение:

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

  2. Макросы времени ($__time, $__timeFilter и т. д.) всегда раскрываются в значения UTC.

  3. Задайте Session Timezone в конфигурации источника данных в соответствии с часовым поясом ваших данных или используйте +00:00 для UTC.

  4. Если ваши отметки времени хранятся в местном времени, преобразуйте их в UTC в запросе:

    SQL 
    SELECT
  CONVERT_TZ(your_datetime_column, 'Your/Timezone', 'UTC') AS time,
  value
FROM your_table

Запрос возвращает слишком много строк

Сообщение об ошибке: “Result set too large” или браузер перестаёт отвечать

Причина: Запрос возвращает больше данных, чем можно эффективно обработать.

Решение:

  1. Добавьте фильтры по времени с помощью $__timeFilter(column), чтобы ограничить данные временным диапазоном дашборда.
  2. Используйте агрегации (AVG, SUM, COUNT) с GROUP BY вместо возврата необработанных строк.
  3. Добавьте условие LIMIT, чтобы ограничить результаты: SELECT ... LIMIT 1000.
  4. Используйте макрос $__timeGroup(), чтобы агрегировать данные по временным интервалам.

Синтаксическая ошибка в инструкции SQL

Сообщение об ошибке: “You have an error in your SQL syntax” с последующими подробностями об ошибке

Причина: SQL-запрос содержит недопустимый синтаксис.

Решение:

  1. Проверьте наличие пропущенных или лишних запятых, скобок или кавычек.
  2. Убедитесь, что зарезервированные слова, используемые как идентификаторы, заключены в обратные кавычки: `table`, `select`.
  3. Убедитесь, что синтаксис переменных шаблонов верен: $variable или ${variable}.
  4. Протестируйте запрос напрямую в клиенте MySQL, чтобы изолировать проблемы, специфичные для Grafana.

Неизвестный столбец в списке полей

Сообщение об ошибке: “Unknown column ‘column_name’ in ‘field list’”

Причина: Указанный столбец не существует в таблице или его имя написано с ошибкой.

Решение:

  1. Проверьте, что имя столбца написано правильно.
  2. Проверьте, что столбец существует в указанной таблице.
  3. Если имя столбца содержит специальные символы или пробелы, заключите его в обратные кавычки: `column-name`.
  4. Убедитесь, что выбрана правильная база данных, если вы ссылаетесь на столбцы без полного пути к таблице.

Выражение CASE даёт сбой на нестандартных строковых типах столбцов

Сообщение об ошибке: Запрос с CASE WHEN возвращает ошибку или неожиданные результаты в Grafana, но работает в других клиентах MySQL

Причина: Драйвер MySQL в Grafana не обрабатывает все подтипы строк MySQL (такие как ENUM, SET, TINYTEXT или MEDIUMTEXT) в выражениях CASE. Драйвер может неправильно вывести тип результата.

Решение:

  1. Используйте CAST() для нормализации столбца к CHAR перед использованием в выражении CASE:

    SQL 
    SELECT
  CASE WHEN CAST(status_column AS CHAR) = 'active' THEN 1 ELSE 0 END AS is_active
FROM my_table

  2. Это известное ограничение драйвера Go MySQL, используемого Grafana. Явное приведение к CHAR обеспечивает согласованную обработку типов.

Проблемы с производительностью

Эти проблемы связаны с медленными запросами или высоким потреблением ресурсов.

Медленное выполнение запросов

Причина: Запросы выполняются долго.

Решение:

  1. Сократите временной диапазон дашборда, чтобы ограничить объём данных.

  2. Добавьте индексы к столбцам, используемым в условиях WHERE и фильтрах по времени:

    SQL 
    CREATE INDEX idx_time ON your_table(time_column);

  3. Используйте агрегации вместо возврата отдельных строк.

  4. Увеличьте параметр Min time interval, чтобы уменьшить количество точек данных.

  5. Изучите план выполнения запроса с помощью EXPLAIN, чтобы выявить узкие места:

    SQL 
    EXPLAIN SELECT * FROM your_table WHERE time_column > NOW() - INTERVAL 1 HOUR;

Исчерпание пула соединений

Сообщение об ошибке: “Too many connections” или “Connection pool exhausted”

Причина: Слишком много одновременных соединений с базой данных.

Решение:

  1. Увеличьте лимит соединений Max open в конфигурации источника данных.

  2. Включите Auto (max idle) для автоматического управления неактивными соединениями.

  3. Уменьшите количество панелей, одновременно запрашивающих один и тот же источник данных.

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

  5. Увеличьте параметр max_connections в MySQL при необходимости:

    SQL 
    SHOW VARIABLES LIKE 'max_connections';
SET GLOBAL max_connections = 200;

Тайм-аут запроса

Сообщение об ошибке: “Query execution was interrupted” или “Lock wait timeout exceeded”

Причина: Запрос выполняется слишком долго и превышает настроенный тайм-аут.

Решение:

  1. Оптимизируйте запрос, добавив подходящие индексы.
  2. Сократите объём запрашиваемых данных, сузив временной диапазон.
  3. Используйте агрегации, чтобы уменьшить размер результирующего набора.
  4. Проверьте наличие блокировок таблиц, которые могут задерживать запрос.

Другие распространённые проблемы

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

Сбои запросов переменных шаблонов

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

Решение:

  1. Убедитесь, что синтаксис запроса переменной — это допустимый SQL, возвращающий один столбец.
  2. Проверьте, что соединение с источником данных работает.
  3. Убедитесь, что у пользователя есть разрешение на доступ к таблицам, указанным в запросе переменной.
  4. Протестируйте запрос в редакторе запросов, прежде чем использовать его как запрос переменной.

Данные выглядят некорректно или смещённо

Причина: Проблемы с форматированием данных или преобразованием типов.

Решение:

  1. Используйте явные псевдонимы столбцов, чтобы обеспечить согласованность имён: SELECT value AS metric.
  2. Проверьте, что числовые столбцы действительно имеют числовые типы, а не строковые.
  3. Проверьте наличие значений NULL, которые могут повлиять на агрегации.
  4. Используйте параметр FILL в макросе $__timeGroup() для обработки пропущенных точек данных.

Специальные символы в именах баз данных или таблиц

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

Решение:

  1. Заключайте идентификаторы со специальными символами в обратные кавычки: `my-database`.`my-table`.
  2. Редактор запросов обрабатывает это автоматически для выборок, но ручные запросы требуют обратных кавычек.
  3. По возможности избегайте использования зарезервированных слов в качестве идентификаторов.

Кэширование запросов нельзя включить для провижиненного источника данных

Причина: Когда источник данных MySQL провижинится через YAML, переключатель кэширования запросов в интерфейсе неактивен. Провижининг через YAML в настоящее время не поддерживает настройку кэширования.

Решение:

  1. Используйте HTTP API Grafana, чтобы включить кэширование запросов для провижиненного источника данных. Отправьте запрос PUT, чтобы обновить источник данных с включённым кэшированием:

    sh 
    curl -X PUT -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_TOKEN>" \
  "https://<GRAFANA_URL>/api/datasources/<DATASOURCE_ID>" \
  -d '{
    "jsonData": {
      "queryCachingTTL": 300
    }
  }'

    Замените <API_TOKEN> на действительный API-токен Grafana, <GRAFANA_URL> на URL вашего экземпляра Grafana, а <DATASOURCE_ID> на числовой идентификатор источника данных. Установите queryCachingTTL в желаемую длительность кэша в секундах.

  2. Получите идентификатор источника данных, вызвав GET /api/datasources/name/<DATA_SOURCE_NAME>.

  3. Настройка кэширования через YAML — это открытый запрос на функцию. Проверяйте текущий статус в Grafana GitHub issues.

Note

Кэширование запросов доступно в Grafana Enterprise и Grafana Cloud. Подробнее см. в разделе Query and resource caching.

Произошла неожиданная ошибка

Сообщение об ошибке: “An unexpected error happened”

Причина: Произошла общая ошибка, для которой нет конкретного сообщения.

Решение:

  1. Проверьте журналы сервера Grafana, чтобы получить больше сведений об ошибке.
  2. Убедитесь, что все параметры конфигурации источника данных верны.
  3. Проверьте соединение с помощью кнопки Save & test.
  4. Убедитесь, что сервер MySQL доступен и отвечает на запросы.
  5. Клиентам Grafana Cloud: обратитесь в службу поддержки за помощью.

Получение дополнительной помощи

Если проблемы сохраняются после выполнения рекомендаций этого руководства:

  1. Проверьте форумы сообщества Grafana на наличие похожих проблем.
  2. Изучите Grafana GitHub issues на наличие известных ошибок.
  3. Включите отладочное логирование в Grafana, чтобы получить подробную информацию об ошибках.
  4. Проверьте журналы ошибок MySQL для получения дополнительных сведений.
  5. Обратитесь в службу поддержки Grafana, если вы клиент Enterprise или Cloud.

При сообщении о проблемах указывайте:

  • Версию Grafana
  • Версию плагина источника данных MySQL, которую можно найти на странице Administration > Plugins. Плагин обновляется независимо от релизов Grafana.
  • Версию MySQL
  • Сообщения об ошибках (удалите конфиденциальную информацию)
  • Шаги воспроизведения
  • Соответствующие примеры запросов (удалите конфиденциальные данные)