14 ODBC 监控

概述

ODBC 监控对应 Zabbix 前端中的 数据库监控 监控项 类型。

ODBC 是一种使用 C 编程语言的中间件 API，用于访问数据库管理系统（DBMS）。 ODBC 概念最初由 Microsoft 开发，随后被移植到其他平台。

Zabbix 可以 query 任何由 ODBC 支持的数据库。 为此，Zabbix 并不直接连接数据库，而是通过 ODBC 接口和在 ODBC 中设置的驱动程序进行连接。 这使得可以更高效地针对多种用途监控不同的数据库（例如，检查特定的数据库队列、使用统计等）。

Zabbix 支持 unixODBC，这是最常用的开源 ODBC API 实现之一。

另请参阅：odbc检查 了解 ODBC 检查相关内容。

安装 unixODBC

安装 unixODBC 的推荐方法是使用 Linux 操作系统默认的软件包仓库。
在最流行的 Linux 发行版中，unixODBC 默认包含在软件包仓库中。
如果软件包不可用，可以从 unixODBC 官方网站获取源文件：http://www.unixodbc.org/download.html。

要安装 unixODBC，请使用您选择系统的软件包管理器：

# For Ubuntu/Debian systems:
apt install unixodbc unixodbc-dev

# For RedHat/Fedora-based systems:
dnf install unixODBC unixODBC-devel

# For SUSE-based systems:
zypper in unixODBC-devel

要编译支持 unixODBC 的 Zabbix，需要安装 unixodbc-dev 或 unixODBC-devel 软件包。 要启用 ODBC 支持，Zabbix 应该使用以下 configuration option 进行编译： 

--with-unixodbc[=ARG] # 使用 ODBC 驱动支持 unixODBC 软件包。

安装 unixODBC 驱动

应为将要监控的数据库安装unixODBC数据库驱动程序。 有关支持的数据库和驱动程序列表，请参阅unixODBC主页：http://www.unixodbc.org/drivers.html。

在某些Linux发行版中，数据库驱动程序包含在软件包仓库中。

MySQL

要安装 MySQL unixODBC 数据库驱动程序，请使用您选择的系统的包管理器：

# For Ubuntu/Debian systems:
apt install odbc-mariadb

# For RedHat/Fedora-based systems:
dnf install mariadb-connector-odbc

# For SUSE-based systems:
zypper install mariadb-connector-odbc

如需在没有包管理器的情况下安装数据库驱动程序，请参阅 MySQL documentation 以获取 mysql-connector-odbc 的说明，或参阅 MariaDB documentation 以获取 mariadb-connector-odbc 的说明。

PostgreSQL

要安装 PostgreSQL unixODBC 数据库驱动程序，请使用您选择系统的包管理器：

# For Ubuntu/Debian systems:
apt install odbc-postgresql

# For RedHat/Fedora-based systems:
dnf install postgresql-odbc

# For SUSE-based systems:
zypper install psqlODBC

如需在没有包管理器的情况下安装数据库驱动程序，请参阅 PostgreSQL documentation。

Oracle

安装unixODBC数据库驱动，请参考Oracle documentation。

MSSQL

若要在 Ubuntu/Debian 系统上安装 MSSQL unixODBC 数据库驱动程序，请使用您选择系统的包管理器：

# For Ubuntu/Debian systems:
apt install tdsodbc

# For RedHat/Fedora-based systems (EPEL packages: https://docs.fedoraproject.org/en-US/epel/):
dnf install epel-release
dnf install freetds

# For SUSE-based systems:
zypper install libtdsodbc0

若要在没有包管理器的情况下安装数据库驱动程序，请参考 FreeTDS user guide。

配置 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

The odbcinst.ini file 列出了已安装的 ODBC 数据库驱动程序。 如果缺少 odbcinst.ini，则需要手动 create。

[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 file。 请注意，支持的参数列表取决于数据库驱动程序（例如，Oracle 数据库可能使用 ServerName 而不是 Server 等）。

[TEST_MYSQL]
Description=MySQL Test Database
Driver=mysql
Server=127.0.0.1
User=root
Password=
Port=3306
Socket=
Database=zabbix
参数 描述
TEST_MYSQL 数据源名称 (DSN)。
Description 数据源描述。
Driver 数据库驱动程序名称（如 odbcinst.ini 中所指定）。
Server 数据库服务器 IP/DNS。
User 用于连接的数据库用户。
Password 数据库用户密码。
Port 数据库连接端口。
Socket 数据库连接套接字。
Database 数据库名称。

有关其他可能的配置参数选项，请参见 MySQL documentation。

odbc.ini file 用于 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 queries），并限制修改操作（如 INSERT、UPDATE 和 DELETE 语句）；适用于数据应保持不变的场景。
Protocol PostgreSQL 后端协议 version（在使用 SSL 连接时将被忽略）。
ShowOidColumn 指定是否在 SQLColumns 中包含 object ID（OID）。
FakeOidIndex 指定是否在 OID 上 create 一个伪造的唯一索引。
RowVersioning 指定应用程序是否应检测在尝试 update 某一行时，该行数据是否已被其他用户修改。请注意，此参数可以加快 update 过程，因为要 update 一行，不需要在 WHERE 子句中指定每一列。
ShowSystemTables 指定数据库驱动程序是否应在 SQLTables 中将系统表视为常规表；有助于提高可访问性，允许查看系统表。
Fetch 指定驱动程序是否应自动使用 declare cursor/fetch 来处理 SELECT 语句，并维护 100 行的缓存。
BoolsAsChar 控制 boolean 类型的映射。
如果设置为“是”，则布尔值将映射为 SQL_CHAR；否则将映射为 SQL_BIT。
SSLmode 指定连接的 SSL 模式。
ConnSettings 在连接时发送到后端的附加设置。
测试 ODBC 连接

要测试ODBC连接是否成功工作，可以使用 isql 工具（包含在 unixODBC 软件包中）：

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

Zabbix前端中的监控项配置

配置一个 数据库监控 概述。

所有必填输入字段均以红色星号标记。

对于数据库监控 监控项，您必须指定以下内容：
类型 在此处选择“数据库监控”。
键值 输入一个受支持的 监控项 键：
db.odbc.select[] - 此 监控项 返回一个值（SQL query 结果的第一行第一列）；
db.odbc.get[] - 此 监控项 以JSON格式返回多行/列；
db.odbc.discovery[] - 此 监控项 返回低级别自动发现数据。
用户名 输入数据库用户名（最多255个字符）。
如果在 odbc.ini 文件中指定了数据库用户名，则此参数为可选。
如果使用了连接 string，且 用户名 字段不为空，则它将作为 UID=<user> 附加到连接 string 中。
密码 输入数据库用户密码（最多255个字符）。
如果密码在 odbc.ini 文件中指定，则此参数为可选。
如果使用了连接 string，且 密码 字段不为空，则它将作为 PWD=<password> 附加到连接 string 中。
自 Zabbix 7.0.3 起，此字段支持特殊字符。

在 Zabbix 7.0.3 之前，如果密码包含分号，则应将其用花括号包裹，例如 {P?;)*word}。在 7.0.3 之后，此情况仍支持包裹密码，但不再必需。密码将在用户名之后作为 UID=<username>;PWD={P?;)*word} 附加到连接 string。要测试最终的 string，您可以运行 run 以下命令：
isql -v -k 'Driver=libmaodbc.so;Database=zabbix;UID=zabbix;PWD={P?;)*word}'
SQL query 输入SQL query。
请注意，使用 db.odbc.select[] 时，query 必须仅返回一个值。
信息类型 在此处选择 query 将返回的信息类型。
如果信息类型选择错误，监控项 将变为不支持状态。

重要注意事项

  • 如果在 server 或 proxy 配置中未启动任何 odbc 轮询器 进程，则数据库监控 监控项 将不再受支持。 要激活 ODBC 轮询器，请在 Zabbix server 配置 file 中设置 StartODBCPollers 参数；或者对于由 proxy 执行的检查，请在 Zabbix proxy 配置文件中设置。
  • 在 配置 表单中，Timeout 参数值将用作 ODBC login 超时和 query 执行超时。 请注意，如果安装的 ODBC 驱动程序不支持这些设置，则可能会忽略这些超时设置。
  • SQL 命令必须像使用 select 语句的任何 query 一样返回结果集。 query 的语法将取决于处理它们的 RDBMS。 对存储过程的请求语法必须以 call 关键字开头。

监控项键详情

不带尖括号的参数为必选参数。带有尖括号 < > 标记的参数为可选参数。

db.odbc.select[<唯一简短描述>,<dsn>,<连接 string>]


返回一个值，即 SQL query 结果第一行的第一列。
返回值：取决于 SQL query。

参数：

  • 唯一简短描述 - 唯一的简短描述，用于标识 监控项（用于触发器等）；
  • dsn - 数据源名称（如 odbc.ini 中指定的）；
  • 连接 string - 连接 string（可以包含驱动程序特定的参数）。

注释：

  • 虽然 dsn 和 connection string 是可选参数，但至少需要其中一个；如果两者都定义了，则会忽略 dsn。
  • 如果 query 返回多于一列，则仅读取第一列。如果 query 返回多于一行，则仅读取第一行。
db.odbc.get[<唯一简短描述>,<dsn>,<连接 string>] {#db.odbc.get}


将SQL query结果转换为JSON array。
返回值：JSON object。

参数：

  • 唯一简短描述 - 唯一的简短描述，用于标识监控项（用于触发器等）；
  • dsn - 数据源名称（在odbc.ini中指定的名称）；
  • 连接string - 连接string（可能包含驱动程序特定的参数）。

备注：

  • 虽然dsn和connection string是可选参数，但至少需要其中一个；如果两者都定义了，则会忽略dsn。
  • 可能以JSON格式返回多行/多列。 此监控项可以用作主监控项，通过一次系统调用收集所有数据，而JSONPath预处理可用于依赖的监控项中提取单个值。 有关返回格式的示例，请参见低级别自动发现中使用的示例。

示例：

# MySQL ODBC驱动程序的连接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>,<连接 string>]


将 SQL query 结果转换为 JSON array，用于 low-level discovery。 query 结果中的列名将被转换为低级别自动发现宏名称，并与发现的字段值配对。 这些宏可用于创建 监控项、触发器等原型。
返回值：JSON object。

参数：

  • 唯一的简短描述 - 用于标识 监控项 的唯一简短描述（用于触发器等）；
  • dsn - 数据源名称（如 odbc.ini 中指定）；
  • 连接 string - 连接 string（可能包含驱动程序特定参数）。

注释：

  • 虽然 dsn 和 connection string 是可选参数，但至少需要其中一个；如果两者都定义了，则会忽略 dsn。

错误消息

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 会尝试将它们连接起来（以 | 分隔），直到达到长度限制为止。