14 ODBC 監視

概要

ODBC監視は、Zabbix Webインターフェースのデータベースモニタアイテムタイプに対応します。

ODBCは、データベース管理システム（DBMS）にアクセスするためのCプログラミング言語のミドルウェアAPIです。
ODBCの概念はMicrosoftによって開発され、その後ほかのプラットフォームにも移植されました。

Zabbixは、ODBCでサポートされている任意のデータベースを照会できます。
そのために、Zabbixはデータベースへ直接接続するのではなく、ODBCで設定されたODBCインターフェースとドライバーを使用します。
これにより、さまざまな目的（たとえば、特定のデータベースキュー、使用統計などの確認）に応じて、異なるデータベースをより効率的に監視できます。

Zabbixは、最も一般的に使用されているオープンソースのODBC API実装の1つであるunixODBCをサポートしています。

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

unixodbc-dev または unixODBC-devel パッケージは、unixODBCサポート付きでZabbixをコンパイルするために必要です。 ODBCサポートを有効にするには、Zabbixを次の設定オプションでコンパイルする必要があります: 

--with-unixodbc[=ARG] # unixODBCパッケージに対してODBCドライバーを使用します。

unixODBCドライバーのインストール

監視対象のデータベースに対して、unixODBCデータベースドライバーをインストールする必要があります。
サポートされているデータベースとドライバーの一覧については、unixODBCのホームページを参照してください: http://www.unixodbc.org/drivers.html。

一部のLinuxディストリビューションでは、データベースドライバーがパッケージリポジトリに含まれています。

MySQL

MySQL unixODBCデータベースドライバーをインストールするには、使用するシステムに応じたパッケージマネージャーを使用します。

# Ubuntu/Debian システムの場合:
apt install odbc-mariadb

# RedHat/Fedora ベースのシステムの場合:
dnf install mariadb-connector-odbc

# SUSE ベースのシステムの場合:
zypper install mariadb-connector-odbc

パッケージマネージャーを使用せずにデータベースドライバーをインストールする場合は、mysql-connector-odbc については MySQL documentation、mariadb-connector-odbc については MariaDB documentation を参照してください。

PostgreSQL

PostgreSQL unixODBCデータベースドライバーをインストールするには、使用するシステムに応じたパッケージマネージャーを使用します。

# Ubuntu/Debianシステムの場合:
apt install odbc-postgresql

# RedHat/Fedoraベースのシステムの場合:
dnf install postgresql-odbc

# SUSEベースのシステムの場合:
zypper install psqlODBC

パッケージマネージャーを使用せずにデータベースドライバーをインストールする場合は、PostgreSQL documentationを参照してください。

Oracle

unixODBCデータベースドライバーをインストールするには、Oracle documentationを参照してください。

MSSQL

MSSQL unixODBCデータベースドライバーをインストールするには、使用しているシステムに応じたパッケージマネージャーを使用します。

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

odbcinst.ini ファイルには、インストールされているODBCデータベースドライバーが一覧表示されます。
odbcinst.ini が存在しない場合は、手動で作成する必要があります。

[TEST_MYSQL]
Description=ODBC for MySQL
Driver=/usr/lib/libmyodbc5.so
FileUsage=1
Parameter Description
TEST_MYSQL データベースドライバー名。
Description データベースドライバーの説明。
Driver データベースドライバーライブラリの場所。
FileUsage データベースドライバーが、ローカルファイルへのアクセス機能のサポートなしでデータベースサーバーへの接続をサポートするか (0)、ファイルからのデータ読み取りをサポートするか (1)、ファイルへのデータ書き込みをサポートするか (2) を決定します。
Threading スレッドのシリアル化レベル。PostgreSQLでサポートされています。
1.6以降、ドライバーマネージャーがスレッドサポート付きでビルドされている場合は、別のドライバーエントリを追加できます。
odbc.ini

odbc.ini ファイルは、データソースの設定に使用されます。
サポートされるパラメータの一覧はデータベースドライバーによって異なることに注意してください（たとえば、Oracleデータベースでは Server の代わりに ServerName を使用する場合があります）。

[TEST_MYSQL]
Description=MySQL Test Database
Driver=mysql
Server=127.0.0.1
User=root
Password=
Port=3306
Socket=
Database=zabbix
Parameter Description
TEST_MYSQL データソース名（DSN）。
Description データソースの説明。
Driver データベースドライバー名（odbcinst.ini で指定）。
Server データベースサーバーのIP/DNS。
User 接続に使用するデータベースユーザー。
Password データベースユーザーのパスワード。
Port データベース接続ポート。
Socket データベース接続ソケット。
Database データベース名。

その他の設定パラメータオプションについては、MySQL documentation を参照してください。

PostgreSQL用の odbc.ini ファイルには、追加のパラメータを含めることができます。

[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 SQLColumns に Object ID（OID）を含めるかどうかを指定します。
FakeOidIndex OID に対して疑似的な一意インデックスを作成するかどうかを指定します。
RowVersioning 行の更新を試みている間に、他のユーザーによってデータが変更されたかどうかをアプリケーションが検出できるようにするかどうかを指定します。このパラメータを使用すると、行を更新する際に WHERE 句ですべての列を個別に指定する必要がなくなるため、更新処理が高速化される場合があります。
ShowSystemTables SQLTables において、データベースドライバーがシステムテーブルを通常のテーブルとして扱うかどうかを指定します。アクセシビリティの向上に役立ち、システムテーブルを参照できるようになります。
Fetch ドライバーが SELECT 文を処理するために declare cursor/fetch を自動的に使用し、100 行のキャッシュを維持するかどうかを指定します。
BoolsAsChar Boolean 型のマッピングを制御します。
"Yes" に設定すると、Boolean 値は SQL_CHAR にマッピングされ、それ以外の場合は SQL_BIT にマッピングされます。
SSLmode 接続の SSL モードを指定します。
ConnSettings 接続時にバックエンドへ送信される追加設定です。
ODBC接続のテスト

ODBC接続が正常に動作しているかどうかをテストするには、isqlユーティリティ（unixODBCパッケージに含まれています）を使用できます。

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

Zabbix Webインターフェースでのアイテム設定

データベース監視のアイテムを設定します。

必須の入力フィールドには、赤いアスタリスクが付いています。

データベース監視アイテムでは、以下を指定する必要があります。
Type ここで「Database monitor」を選択します。
Key サポートされているアイテムキーのいずれかを入力します。
db.odbc.select[] - このアイテムは1つの値を返します（SQLクエリ結果の最初の行の最初の列）。
db.odbc.get[] - このアイテムは複数の行/列をJSON形式で返します。
db.odbc.discovery[] - このアイテムはローレベルディスカバリデータを返します。
User name データベースのユーザー名を入力します（最大255文字）。
このパラメータは、データベースのユーザー名が odbc.ini ファイルで指定されている場合は省略可能です。
接続文字列を使用していて、User name フィールドが空でない場合は、UID=<user> として接続文字列に追加されます。
Password データベースのユーザーパスワードを入力します（最大255文字）。
このパラメータは、パスワードが odbc.ini ファイルで指定されている場合は省略可能です。
接続文字列を使用していて、Password フィールドが空でない場合は、PWD=<password> として接続文字列に追加されます。
このフィールドでは特殊文字を使用できます。
パスワードは、たとえば UID=<username>;PWD=P?;)*word のように、ユーザー名の後に接続文字列へ追加されます。
生成される文字列をテストするには、次のコマンドを実行できます。
isql -v -k 'Driver=libmaodbc.so;Database=zabbix;UID=zabbix;PWD=P?;)*word'
SQL query SQLクエリを入力します。
db.odbc.select[] では、クエリは1つの値のみを返す必要があることに注意してください。
Type of information ここでクエリによって返される情報の型を選択します。
情報の型が正しく選択されていない場合、アイテムは未サポートになります。

重要な注意事項

  • サーバーまたはプロキシの設定で odbc poller プロセスが起動されていない場合、データベース監視アイテムは未サポートになります。 ODBC poller を有効にするには、Zabbix server 設定ファイル、またはプロキシによって実行されるチェックの場合は Zabbix proxy 設定ファイルで、StartODBCPollers パラメータを設定してください。
  • アイテム設定 フォームの Timeout パラメータ値は、ODBC のログインタイムアウトおよびクエリ実行タイムアウトとして使用されます。 インストールされている ODBC ドライバーがこれらをサポートしていない場合、これらのタイムアウト設定は無視される可能性があることに注意してください。
  • SQL コマンドは、select 文を使用するクエリと同様に、結果セットを返す必要があります。 クエリ構文は、それを処理する RDBMS によって異なります。 ストアドプロシージャへのリクエスト構文は、call キーワードで開始する必要があります。

アイテムキーの詳細

山かっこなしのパラメータは必須です。山かっこ < > で示されたパラメータは任意です。

db.odbc.select[<一意の短い説明>,<dsn>,<接続文字列>]


1つの値、つまりSQLクエリ結果の最初の行の最初の列を返します。
戻り値: SQLクエリに応じます。

パラメータ:

  • 一意の短い説明 - アイテムを識別するための一意の短い説明（トリガーなどで使用）;
  • dsn - データソース名（odbc.iniで指定）;
  • 接続文字列 - 接続文字列（ドライバー固有の引数を含む場合があります）。

コメント:

  • dsn と 接続文字列 はオプションのパラメータですが、少なくともどちらか一方は必須です。両方が定義されている場合、dsn は無視されます。
  • クエリが複数の列を返す場合は、最初の列のみが読み取られます。クエリが複数の行を返す場合は、最初の行のみが読み取られます。
db.odbc.get[<一意の短い説明>,<dsn>,<接続文字列>]


SQLクエリの結果をJSON配列に変換します。
戻り値: JSON object。

パラメータ:

  • 一意の短い説明 - アイテムを識別するための一意の短い説明（トリガーなどで使用）;
  • dsn - データソース名（odbc.ini で指定）;
  • 接続文字列 - 接続文字列（ドライバー固有の引数を含む場合があります）。

コメント:

  • dsn と 接続文字列 はどちらもオプションのパラメータですが、少なくともどちらか一方は必須です。両方が定義されている場合、dsn は無視されます。
  • JSON形式で複数の行/列が返される場合があります。 このアイテムは、1回のシステムコールですべてのデータを収集するマスターアイテムとして使用でき、個々の値を抽出するために、依存アイテムで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 object。

パラメータ:

  • 一意の短い説明 - アイテムを識別するための一意の短い説明（トリガーなどで使用）;
  • dsn - データソース名（odbc.iniで指定）;
  • 接続文字列 - 接続文字列（ドライバー固有の引数を含む場合があります）。

コメント:

  • dsn と 接続文字列 はどちらもオプションのパラメータですが、少なくとも一方は必須です。両方が定義されている場合、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は長さの制限が許す範囲で、それらを（|で区切って）連結しようとします。