14 ODBC-bewaking

Overzicht

ODBC-monitoring komt overeen met het Database monitor itemtype in de Zabbix-frontend.

ODBC is een middle-ware API in de programmeertaal C voor het benaderen van databasebeheersystemen (DBMS). Het ODBC-concept is ontwikkeld door Microsoft en later overgebracht naar andere platforms.

Zabbix kan elke database bevragen die wordt ondersteund door ODBC. Om dit te doen, maakt Zabbix geen directe verbinding met de databases, maar gebruikt het de ODBC-interface en drivers die zijn geconfigureerd in ODBC. Deze functie maakt efficiëntere monitoring van verschillende databases mogelijk voor meerdere doeleinden - bijvoorbeeld het controleren van specifieke database-wachtrijen, gebruiksstatisitieken en dergelijke. Zabbix ondersteunt unixODBC, wat een van de meest gebruikte open source ODBC API-implementaties is.

unixODBC installeren

De aanbevolen manier om unixODBC te installeren is door de standaard pakketbronnen van het Linux-besturingssysteem te gebruiken. In de meest populaire Linux-distributies is unixODBC standaard opgenomen in het pakketrepository. Als het niet beschikbaar is, kan het worden verkregen via de unixODBC-website: http://www.unixodbc.org/download.html.

Het installeren van unixODBC op RedHat/Fedora-gebaseerde systemen met behulp van het dnf-pakketbeheer:

shell> dnf -y install unixODBC unixODBC-devel

Het installeren van unixODBC op SUSE-gebaseerde systemen met behulp van het zypper-pakketbeheer:

# zypper in unixODBC-devel

unixODBC installeren

De aanbevolen manier om unixODBC te installeren is door de standaard pakketbronnen van het Linux-besturingssysteem te gebruiken. In de meest populaire Linux-distributies is unixODBC standaard opgenomen in het pakketrepository. Als het niet beschikbaar is, kan het worden verkregen via de unixODBC-website: http://www.unixodbc.org/download.html.

Het installeren van unixODBC op RedHat/Fedora-gebaseerde systemen met behulp van het dnf-pakketbeheer:

shell> dnf -y install unixODBC unixODBC-devel

Het installeren van unixODBC op SUSE-gebaseerde systemen met behulp van het zypper-pakketbeheer:

# zypper in unixODBC-devel

MySQL

To install the MySQL unixODBC database driver, use the package manager for the system of your choice:

# For Ubuntu/Debian systems:
       apt install odbc-mariadb
       
       # For RedHat/Fedora-based systems:
       dnf install mysql-connector-odbc
       
       # For SUSE-based systems:
       zypper install MyODBC-unixODBC

To install the database driver without a package manager, refer to MySQL documentation.

PostgreSQL

To install the PostgreSQL unixODBC database driver for RedHat/Fedora-based systems, use the dnf package manager:

dnf install postgresql-odbc

For other systems, please refer to PostgreSQL documentation.

Oracle

To install the unixODBC database driver, please refer to Oracle documentation.

MSSQL

To install the MSSQL unixODBC database driver for RedHat/Fedora-based systems, use the dnf package manager:

dnf -y install freetds unixODBC

For other systems, please refer to FreeTDS user guide.

unixODBC configureren

De ODBC-configuratie wordt uitgevoerd door de odbcinst.ini- en odbc.ini-bestanden aan te passen. Om de locatie van het configuratiebestand te verifiëren, typt u:

shell> odbcinst -j

odbcinst.ini wordt gebruikt om de geïnstalleerde ODBC-database-stuurprogramma's op te lijsten:

[mysql]
       Description = ODBC voor MySQL
       Driver      = /usr/lib/libmyodbc5.so

Parameterdetails:

odbc.ini wordt gebruikt om gegevensbronnen te definiëren:

[test]
       Description = MySQL testdatabase
       Driver      = mysql
       Server      = 127.0.0.1
       User        = root
       Password    =
       Port        = 3306
       Database    = zabbix

Parameterdetails:

Om te controleren of de ODBC-verbinding succesvol werkt, moet een verbinding met de database worden getest. Dit kan worden gedaan met het hulpprogramma isql (inbegrepen in het unixODBC-pakket):

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

odbcinst.ini

The odbcinst.ini file lists the installed ODBC database drivers. If odbcinst.ini is missing, it is necessary to create it manually.

[TEST_MYSQL]
       Description=ODBC for MySQL
       Driver=/usr/lib/libmyodbc5.so
       FileUsage=1

odbc.ini

The odbc.ini file is used to configure data sources.

[TEST_MYSQL]
       Description=MySQL Test Database
       Driver=mysql
       Server=127.0.0.1
       User=root
       Password=
       Port=3306
       Socket=
       Database=zabbix

For other possible configuration parameter options, see MySQL documentation.

The odbc.ini file for PostgreSQL may contain additional parameters:

[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=

Testing ODBC connection

To test if the ODBC connection is working successfully, you can use the isql utility (included in the unixODBC package):

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

Itemconfiguratie in de Zabbix frontend

Configureer een database monitoring item.

Alle verplichte invoervelden zijn gemarkeerd met een rode asterisk.

Specifiek voor database monitoring items moet je het volgende invoeren:

Item key details

Parameters without angle brackets are mandatory. Parameters marked with angle brackets < > are optional.

db.odbc.select[<unique short description>,<dsn>,<connection string>]

Returns one value, i.e. the first column of the first row of the SQL query result. Return value: depending on the SQL query.

Parameters:

• unique short description - a unique short description to identify the item (for use in triggers, etc);
• dsn - the data source name (as specified in odbc.ini);
• connection string - the connection string (may contain driver-specific arguments).

Comments:

• Although dsn and connection string are optional parameters, at least one of them must be present. If both data source name (DSN) and connection string are defined, the DSN will be ignored.
• If a query returns more than one column, only the first column is read. If a query returns more than one line, only the first line is read.

db.odbc.get[<unique short description>,<dsn>,<connection string>]

Transforms the SQL query result into a JSON array.
Return value: JSON object.

Parameters:

• unique short description - a unique short description to identify the item (for use in triggers, etc);
• dsn - the data source name (as specified in odbc.ini);
• connection string - the connection string (may contain driver-specific arguments).

Comments:

• Although dsn and connection string are optional parameters, at least one of them must be present. If both data source name (DSN) and connection string are defined, the DSN will be ignored.
• Multiple rows/columns in JSON format may be returned. This item may be used as a master item that collects all data in one system call, while JSONPath preprocessing may be used in dependent items to extract individual values. For more information, see an example of the returned format, used in low-level discovery.

Example:

db.odbc.get[MySQL example,,"Driver=/usr/local/lib/libmyodbc5a.so;Database=master;Server=127.0.0.1;Port=3306"] #connection for MySQL ODBC driver 5

db.odbc.discovery[<unique short description>,<dsn>,<connection string>]

Transforms the SQL query result into a JSON array, used for low-level disovery. The column names from the query result are turned into low-level discovery macro names paired with the discovered field values. These macros can be used in creating item, trigger, etc prototypes.
Return value: JSON object.

Parameters:

• unique short description - a unique short description to identify the item (for use in triggers, etc);
• dsn - the data source name (as specified in odbc.ini);
• connection string - the connection string (may contain driver-specific arguments).

Comments:

• Although dsn and connection string are optional parameters, at least one of them must be present. If both data source name (DSN) and connection string are defined, the DSN will be ignored.

Belangrijke aantekeningen

• Database monitoring items worden niet ondersteund als er geen odbc poller processen zijn gestart in de server- of proxyconfiguratie. Om ODBC-pollers te activeren, stel je de parameter StartODBCPollers in in het Zabbix server configuratiebestand, of voor checks die worden uitgevoerd door een proxy, in het Zabbix proxy configuratiebestand.
• Zabbix beperkt de uitvoeringstijd van de query niet. Het is aan de gebruiker om query's te kiezen die in een redelijke tijd kunnen worden uitgevoerd.
• De waarde van de parameter Timeout van de Zabbix-server wordt gebruikt als de ODBC-login-timeout (let op dat afhankelijk van de ODBC-drivers de instelling van de login-timeout mogelijk wordt genegeerd).
• Het SQL-commando moet een resultaatset retourneren, net als elke query met select .... De syntaxis van de query hangt af van het RDBMS dat ze zal verwerken. De syntaxis van een aanvraag naar een opgeslagen procedure moet beginnen met het trefwoord call.

Foutmeldingen

ODBC-foutmeldingen zijn gestructureerd in velden om gedetailleerde informatie te verstrekken. Bijvoorbeeld:

Kan ODBC-query niet uitvoeren: [SQL_ERROR]:[42601][7][ERROR: syntax error at or near ";"; Error while executing the query]
       └───────────┬───────────┘  └────┬────┘ └──┬──┘└─────────────────────────────┬─────────────────────────────────────┘
                   │                   │         │    └─ Native foutcode            └─ Native foutbericht
                   │                   │         └─ SQLState
                   └─ Zabbix bericht   └─ ODBC retourcode

Merk op dat de lengte van het foutbericht beperkt is tot 2048 bytes, dus het bericht kan worden afgekapt. Als er meer dan één ODBC-diagnostisch record is, probeert Zabbix ze samen te voegen (gescheiden door |) zolang de lengtelimiet dat toelaat.