14. ODBC мониторинг

Обзор

ODBC мониторинг соответствует типу элемента данных Монитор баз данных в веб-интерфейсе Zabbix.

ODBC — это API на языке программирования Cи к промежуточной прослойке для доступа к системам управления базами данных (DBMS). Концепт ODBC был разработан Microsoft и в дальнейшем портирован на другие платформы.

Zabbix может выполнять запросы к любой базе данных, которая поддерживается ODBC. Чтобы это сделать, Zabbix не подключается напрямую к базам данных, он использует интерфейс ODBC и драйверы, установленные в ODBC. Это позволяет с большей эффективностью мониторить различные базы данных с разнообразными целями (например, проверка специфичных запросов к базе данных, статистика использования и прочее).

Zabbix поддерживает unixODBC, которая является одной из наиболее часто используемых реализаций API ODBC с открытым исходным кодом.

Смотрите также известные проблемы, связанные с ODBC проверками.

Установка unixODBC

Предлагаемый вариант установки unixODBC состоит из использования репозиториев пакетов по умолчанию в операционной системе Linux. В наиболее популярные дистрибутивы Linux unixODBC добавлен в репозитории пакетов по умолчанию. Если пакет недоступен, его исходный код можно получить на домашней странице UnixODBC: http://www.unixodbc.org/download.html.

Чтобы установить unixODBC, используйте менеджер пакетов для выбранной вами системы:

# Для систем Ubuntu/Debian:
       apt install unixodbc unixodbc-dev
       
       # Для систем на базе RedHat/Fedora:
       dnf install unixODBC unixODBC-devel
       
       # Для систем на базе SUSE:
       zypper in unixODBC-devel

Для компиляции Zabbix с поддержкой unixODBC требуется пакет unixodbc-dev или unixODBC-devel. Чтобы включить поддержку ODBC, Zabbix следует скомпилировать со следующей опцией конфигурации:

--with-unixodbc[=ARG] # Использовать драйвер ODBC с пакетом unixODBC.

Установка драйверов unixODBC

Драйвер unixODBC базы данных должен быть установлен для базы данных, которая будет наблюдаться. Для списка поддерживаемых баз данных и драйверов обратитесь к домашней странице unixODBC: http://www.unixodbc.org/drivers.html.

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

MySQL

Чтобы установить драйвер unixODBC базы данных MySQL, используйте менеджер пакетов для выбранной вами системы:

# Для систем Ubuntu/Debian:
       apt install odbc-mariadb
       
       # Для систем на базе RedHat/Fedora:
       dnf install mariadb-connector-odbc
       
       # Для систем на базе SUSE:
       zypper install mariadb-connector-odbc

Чтобы установить драйвер базы данных без менеджера пакетов, обратитесь к документации MySQL [en] для mysql-connector-odbc, или документации MariaDB [en] для mariadb-connector-odbc.

PostgreSQL

Чтобы установить драйвер unixODBC базы данных PostgreSQL, используйте менеджер пакетов для выбранной вами системы:

# Для систем Ubuntu/Debian:
       apt install odbc-postgresql
       
       # Для систем на базе RedHat/Fedora:
       dnf install postgresql-odbc
       
       # Для систем на базе SUSE:
       zypper install psqlODBC

Чтобы установить драйвер базы данных без менеджера пакетов, обратитесь к документации PostgreSQL [en].

Oracle

Чтобы установить драйвер базы данных unixODBC, обратитесь к документации Oracle [en].

MSSQL

Чтобы установить драйвер unixODBC базы данных MSSQL для систем Ubuntu/Debian, используйте менеджер пакетов для выбранной вами системы:

# Для систем Ubuntu/Debian:
       apt install tdsodbc
       
       # Для систем на базе RedHat/Fedora (пакеты EPEL: https://docs.fedoraproject.org/en-US/epel/):
       dnf install epel-release
       dnf install freetds
       
       # Для систем на базе SUSE:
       zypper install libtdsodbc0

Чтобы установить драйвер базы данных без менеджера пакетов, обратитесь к руководству пользователя FreeTDS [en].

Настройка unixODBC

Чтобы настроить unixODBC, необходимо отредактировать файлы odbcinst.ini и odbc.ini. Вы можете проверить расположение этих файлов, выполнив следующую команду:

odbcinst -j

Результат команды должен содержать информацию наподобие следующей:

unixODBC 2.3.9
       DRIVERS............: /etc/odbcinst.ini
       SYSTEM DATA SOURCES: /etc/odbc.ini
       FILE DATA SOURCES..: /etc/ODBCDataSources
odbcinst.ini

Файл odbcinst.ini содержит список установленных драйверов баз данных ODBC. Если odbcinst.ini отсутствует, его необходимо создать вручную.

[TEST_MYSQL]
       Description=ODBC for MySQL
       Driver=/usr/lib/libmyodbc5.so
       FileUsage=1
Параметр Описание
TEST_MYSQL Имя драйвера базы данных.
Description Описание драйвера базы данных.
Driver Местоположение библиотеки драйвера базы данных.
FileUsage Определяет, поддерживает ли драйвер базы данных подключение к серверу базы данных без поддержки доступа к локальным файлам (0); поддерживает чтение данных из файлов (1); поддерживает запись данных в файлы (2).
Threading Уровень сериализации потоков. Поддерживается для PostgreSQL.
Начиная с версии 1.6, если менеджер драйверов собран с поддержкой потоков, вы можете добавить еще одну запись драйвера.
odbc.ini

Файл odbc.ini используется для настройки источников данных.

[TEST_MYSQL]
       Description=MySQL Test Database
       Driver=mysql
       Server=127.0.0.1
       User=root
       Password=
       Port=3306
       Socket=
       Database=zabbix
Параметр Описание
TEST_MYSQL Имя источника данных (Data source name, DSN).
Description Описание источника данных.
Driver Имя драйвера базы данных (как указано в odbcinst.ini).
Server IP/DNS сервера базы данных.
User Пользователь базы данных для подключения.
Password Пароль пользователя базы данных.
Port Порт подключения к базе данных.
Socket Сокет подключения к базе данных.
Database Имя базы данных.

Другие возможные параметры конфигурации смотрите в документации MySQL [en].

Файл odbc.ini для PostgreSQL может содержать дополнительные параметры:

[TEST_PSQL]
       Description=PostgreSQL Test Database
       Driver=postgresql
       Username=zbx_test
       Password=zabbix
       Servername=127.0.0.1
       Database=zabbix
       Port=5432
       ReadOnly=No
       Protocol=7.4+
       ShowOidColumn=No
       FakeOidIndex=No
       RowVersioning=No
       ShowSystemTables=No
       Fetch=Yes
       BoolsAsChar=Yes
       SSLmode=Require
       ConnSettings=
Параметр Описание
ReadOnly Указывает, разрешает ли подключение к базе данных только операции чтения (запросы SELECT) и ограничивает ли изменения (операторы INSERT, UPDATE и DELETE); полезно для сценариев, где данные должны оставаться неизменными.
Protocol Версия внутреннего протокола PostgreSQL (игнорируется при использовании SSL-соединений).
ShowOidColumn Указывает, следует ли включать идентификатор объекта (OID) в SQLColumns.
FakeOidIndex Указывает, следует ли создавать фиктивный уникальный индекс для OID.
RowVersioning Указывает, следует ли разрешить приложениям определять, были ли данные изменены другими пользователями при попытке обновления строки. Обратите внимание, что этот параметр может ускорить процесс обновления, поскольку для обновления строки не нужно указывать каждый отдельный столбец в условии WHERE.
ShowSystemTables Указывает, должен ли драйвер базы данных обрабатывать системные таблицы как обычные таблицы в SQLTables; полезно для обеспечения доступности, позволяя просматривать системные таблицы.
Fetch Указывает, должен ли драйвер автоматически использовать декларацию курсора/выборки для обработки операторов SELECT и поддерживать кэш в 100 строк.
BoolsAsChar Управляет отображением логических типов.
Если установлено значение «Yes», логические типы отображаются на SQL_CHAR; в противном случае они отображаются на SQL_BIT.
SSLmode Указывает режим SSL для соединения.
ConnSettings Дополнительные настройки, отправляемые на бэкенд при соединении.
Тестирование соединения ODBC

Чтобы проверить, работает ли соединение ODBC успешно, можно использовать утилиту isql (входит в пакет unixODBC):

isql test
       +---------------------------------------+
       | Connected!                            |
       |                                       |
       | sql-statement                         |
       | help [tablename]                      |
       | quit                                  |
       |                                       |
       +---------------------------------------+

Настройка элемента данных в веб-интерфейсе Zabbix

Настройка элемента данных Монитор баз данных.

Все обязательные поля ввода отмечены красной звёздочкой.

Для элементов данных мониторинга баз данных вы должны указать:

Тип (Type) Выберите здесь «Монитор баз данных».
Ключ
(Key)
Введите один из поддерживаемых ключей элементов данных:
db.odbc.select[] — этот элемент данных возвращает одно значение (первый столбец первой строки результата SQL-запроса);
db.odbc.get[] — этот элемент данных возвращает несколько строк/столбцов в формате JSON;
db.odbc.discovery[] — этот элемент данных возвращает данные низкоуровневого обнаружения.
Имя пользователя
(User name)
Введите имя пользователя для доступа к базе данных (до 255 символов).
Этот параметр необязателен, если имя пользователя базы данных указано в файле odbc.ini.
Если используется строка подключения и поле Имя пользователя непустое, тогда имя пользователя добавляется к строке подключения как UID=<пользователь>.
Пароль
(Password)
Введите пароль пользователя для доступа к базе данных (до 255 символов).
Этот параметр необязателен, если пароль указан в файле odbc.ini.
Если используется строка подключения и поле Пароль непустое, тогда пароль добавляется к строке подключения как PWD=<пароль>.
Начиная с версии Zabbix 7.0.3, в этом поле поддерживаются специальные символы.

До версии 7.0.3, если пароль содержал точку с запятой, его необходимо было заключить в фигурные скобки, например: {P?;)*word}. После 7.0.3 обрамление пароля фигурными скобками в этом случае всё ещё поддерживается, но не является обязательным. Пароль будет добавлен к строке подключения после имени пользователя как UID=<username>;PWD={P?;)*word}. Чтобы протестировать полученную строку, можно выполнить следующую команду:
isql -v -k 'Driver=libmaodbc.so;Database=zabbix;UID=zabbix;PWD={P?;)*word}'
SQL запрос
(SQL query)
Введите необходимый SQL запрос.
Обратите внимание, что для элемента данных db.odbc.select[] запрос должен возвращать только одно значение.
Тип информации
(Type of information)
Выберите здесь тип информации, которая возвращается запросом.
Если тип информации выбран неверно, элемент данных станет неподдерживаемым.

Подробности ключей элементов данных

Параметры без угловых скобок обязательны. Параметры, обозначенные угловыми скобками < >, опциональны.

db.odbc.select[<уникальное короткое описание>,<dsn>,<строка подключения>]


Возвращает одно значение, то есть первый столбец первой строки результата SQL запроса.
Возвращаемое значение: Зависит от SQL запроса.

Параметры:

  • уникальное короткое описание — уникальное короткое описание, чтобы идентифицировать элемент данных (для использования в триггерах и т. д.);
  • dsn — имя источника данных (как указано в odbc.ini);
  • строка подключения — строка подключения (может содержать специфичные для драйверов аргументы).

Комментарии:

  • Хотя dsn и строка подключения — опциональные параметры, по крайней мере один из них должен присутствовать; если заданы оба, то dsn будет игнорироваться.
  • Если запрос возвращает более одного столбца, будет прочитан только первый столбец. Если запрос возвращает более одной строки, будет прочитана только первая строка.
db.odbc.get[<уникальное короткое описание>,<dsn>,<строка подключения>]


Преобразует результат SQL-запроса в массив JSON.
Возвращаемое значение: Объект JSON.

Параметры:

  • уникальное короткое описание — уникальное короткое описание, чтобы идентифицировать элемент данных (для использования в триггерах и т. д.);
  • dsn — имя источника данных (как указано в odbc.ini);
  • строка подключения — строка подключения (может содержать специфичные для драйверов аргументы).

Комментарии:

  • Хотя dsn и строка подключения — опциональные параметры, по крайней мере один из них должен присутствовать; если заданы оба, то dsn будет игнорироваться.
  • Может быть возвращено несколько строк/столбцов в формате JSON. Этот элемент данных можно использовать в качестве основного элемента данных, который собирает все данные за один системный вызов, а предварительную обработку JSONPath можно использовать в зависимых элементах данных для извлечения отдельных значений. Для получения более подробных сведений смотрите пример возвращаемого формата, использованного в низкоуровневом обнаружении.

Пример:

# Подключение с использованием MySQL ODBC driver 5:
       db.odbc.get[MySQL example,,"Driver=/usr/local/lib/libmyodbc5a.so;Database=master;Server=127.0.0.1;Port=3306"]
db.odbc.discovery[<уникальное короткое описание>,<dsn>,<строка подключения>]


Преобразует результат SQL-запроса в массив JSON, используемый для низкоуровневого обнаружения. Имена столбцов из результата запроса преобразуются в имена макросов низкоуровневого обнаружения, спаренных со значениями обнаруженных полей. Эти макросы можно использовать при создании прототипов элементов данных, триггеров и т. д.
Возвращаемое значение: Объект JSON.

Параметры:

  • уникальное короткое описание — уникальное короткое описание, чтобы идентифицировать элемент данных (для использования в триггерах и т. д.);
  • dsn — имя источника данных (как указано в odbc.ini);
  • строка подключения — строка подключения (может содержать специфичные для драйверов аргументы).

Комментарии:

  • Хотя dsn и строка подключения — опциональные параметры, по крайней мере один из них должен присутствовать; если заданы оба, то dsn будет игнорироваться.

Важные замечания

  • Элементы данных монитора баз данных станут неподдерживаемыми, если процессы odbc poller не запускаются в конфигурации сервера или прокси. Чтобы включить ODBC поллеры, задайте параметр StartODBCPollers в файле конфигурации Zabbix сервера или, если проверки выполняются на стороне прокси, в файле конфигурации Zabbix прокси.
  • Значение параметра Timeout из диалога настроек элемента данных используется как время ожидания выполнения входа в ODBC и время ожидания выполнения запроса. Обратите внимание, что эти настройки времени ожидания могут быть проигнорированы, если установленный драйвер ODBC их не поддерживает.
  • SQL команда должна вернуть набор данных, как и любой запрос с использованием оператора select. Синтаксис запроса будет зависеть от РСУБД, которая будет его обрабатывать. Синтаксис запроса к хранимой процедуре должен начинаться с ключевого слова call.

Сообщения об ошибках

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

Cannot execute ODBC query: [SQL_ERROR]:[42601][7][ERROR: syntax error at or near ";"; Error while executing the query]
  • «Cannot execute ODBC query» — сообщение Zabbix
  • «[SQL_ERROR]» — код, возвращаемый ODBC
  • «[42601]» — SQLState
  • «[7]» — исходный код ошибки
  • «[ERROR: syntax error at or near ";"; Error while executing the query]» — исходное сообщение об ошибке

Обратите внимание, что длина сообщения об ошибке ограничена 2048 байтами, поэтому сообщение может быть усечено. Если имеется более одной диагностической записи ODBC, Zabbix пытается их скомпоновать (разделяя символом |), насколько позволяет ограничение по длине.