14 Surveillance ODBC

Présentation

La supervision ODBC correspond au type d’élément Database monitor dans l’interface Zabbix.

ODBC est une API middleware du langage de programmation C permettant d’accéder aux systèmes de gestion de bases de données (SGBD). Le concept ODBC a été développé par Microsoft puis porté sur d’autres plateformes.

Zabbix peut interroger toute base de données prise en charge par ODBC. Pour cela, Zabbix ne se connecte pas directement aux bases de données, mais utilise l’interface ODBC et les pilotes configurés dans ODBC. Cela permet une supervision plus efficace de différentes bases de données à des fins multiples (par exemple, vérifier des files d’attente spécifiques de base de données, des statistiques d’utilisation, etc.).

Zabbix prend en charge unixODBC, qui est l’une des implémentations open source de l’API ODBC les plus couramment utilisées.

Voir aussi : problèmes connus pour les vérifications ODBC.

Installation de unixODBC

La méthode recommandée pour installer unixODBC consiste à utiliser les dépôts de paquets par défaut du système d’exploitation Linux. Dans les distributions Linux les plus populaires, unixODBC est inclus par défaut dans le dépôt de paquets. Si les paquets ne sont pas disponibles, les fichiers source peuvent être obtenus sur la page d’accueil de unixODBC : http://www.unixodbc.org/download.html.

Pour installer unixODBC, utilisez le gestionnaire de paquets du système de votre choix :

# Pour les systèmes Ubuntu/Debian :
apt install unixodbc unixodbc-dev

# Pour les systèmes basés sur RedHat/Fedora :
dnf install unixODBC unixODBC-devel

# Pour les systèmes basés sur SUSE :
zypper in unixODBC-devel

Le paquet unixodbc-dev ou unixODBC-devel est nécessaire pour compiler Zabbix avec la prise en charge de unixODBC. Pour activer la prise en charge d’ODBC, Zabbix doit être compilé avec l’option de configuration suivante : 

--with-unixodbc[=ARG] # Utiliser le pilote ODBC avec le paquet unixODBC.

Installation des pilotes unixODBC

Le pilote de base de données unixODBC doit être installé pour la base de données qui sera surveillée. Pour obtenir la liste des bases de données et des pilotes pris en charge, consultez la page d’accueil de unixODBC : http://www.unixodbc.org/drivers.html.

Dans certaines distributions Linux, les pilotes de base de données sont inclus dans les dépôts de paquets.

MySQL

Pour installer le pilote de base de données MySQL unixODBC, utilisez le gestionnaire de paquets du système de votre choix :

# Pour les systèmes Ubuntu/Debian :
apt install odbc-mariadb

# Pour les systèmes basés sur RedHat/Fedora :
dnf install mariadb-connector-odbc

# Pour les systèmes basés sur SUSE :
zypper install mariadb-connector-odbc

Pour installer le pilote de base de données sans gestionnaire de paquets, veuillez consulter la documentation MySQL pour mysql-connector-odbc, ou la documentation MariaDB pour mariadb-connector-odbc.

PostgreSQL

Pour installer le pilote de base de données PostgreSQL unixODBC, utilisez le gestionnaire de paquets du système de votre choix :

# Pour les systèmes Ubuntu/Debian :
apt install odbc-postgresql

# Pour les systèmes basés sur RedHat/Fedora :
dnf install postgresql-odbc

# Pour les systèmes basés sur SUSE :
zypper install psqlODBC

Pour installer le pilote de base de données sans gestionnaire de paquets, veuillez consulter la documentation PostgreSQL.

Oracle

Pour installer le pilote de base de données unixODBC, veuillez consulter la documentation Oracle.

MSSQL

Pour installer le pilote de base de données MSSQL unixODBC, utilisez le gestionnaire de paquets du système de votre choix :

# Pour les systèmes Ubuntu/Debian :
apt install tdsodbc

# Pour les systèmes basés sur RedHat/Fedora (paquets EPEL : https://docs.fedoraproject.org/en-US/epel/) :
dnf install epel-release
dnf install freetds

# Pour les systèmes basés sur SUSE :
zypper install libtdsodbc0

Pour installer le pilote de base de données sans gestionnaire de paquets, veuillez consulter le guide de l’utilisateur FreeTDS.

Configuration de unixODBC

Pour configurer unixODBC, vous devez modifier les fichiers odbcinst.ini et odbc.ini. Vous pouvez vérifier l’emplacement de ces fichiers en exécutant la commande suivante :

odbcinst -j

Le résultat de la commande doit contenir des informations similaires à ce qui suit :

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

Le fichier odbcinst.ini répertorie les pilotes de base de données ODBC installés. Si odbcinst.ini est absent, il est nécessaire de le créer manuellement.

[TEST_MYSQL]
Description=ODBC for MySQL
Driver=/usr/lib/libmyodbc5.so
FileUsage=1
Parameter Description
TEST_MYSQL Nom du pilote de base de données.
Description Description du pilote de base de données.
Driver Emplacement de la bibliothèque du pilote de base de données.
FileUsage Détermine si le pilote de base de données prend en charge la connexion à un serveur de base de données sans prise en charge de l'accès aux fichiers locaux (0) ; prend en charge la lecture des données à partir de fichiers (1) ; prend en charge l'écriture des données dans des fichiers (2).
Threading Niveau de sérialisation des threads. Pris en charge pour PostgreSQL.
Depuis la version 1.6, si le gestionnaire de pilotes est compilé avec la prise en charge des threads, vous pouvez ajouter une autre entrée de pilote.
odbc.ini

Le fichier odbc.ini est utilisé pour configurer les sources de données. Notez que la liste des paramètres pris en charge dépend du pilote de base de données (par exemple, les bases de données Oracle peuvent utiliser ServerName au lieu de Server, etc.).

[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 Nom de la source de données (DSN).
Description Description de la source de données.
Driver Nom du pilote de base de données (tel que spécifié dans odbcinst.ini).
Server IP/DNS du serveur de base de données.
User Utilisateur de la base de données pour la connexion.
Password Mot de passe de l’utilisateur de la base de données.
Port Port de connexion à la base de données.
Socket Socket de connexion à la base de données.
Database Nom de la base de données.

Pour d’autres options possibles de paramètres de configuration, consultez la documentation MySQL.

Le fichier odbc.ini pour PostgreSQL peut contenir des paramètres supplémentaires :

[TEST_PSQL]
Description=Base de données de test PostgreSQL
Driver=postgresql
Username=zbx_test
Password=zabbix
Servername=127.0.0.1
Database=zabbix
Port=5432
ReadOnly=No
Protocol=8.0+
ShowOidColumn=No
FakeOidIndex=No
RowVersioning=No
ShowSystemTables=No
Fetch=Yes
BoolsAsChar=Yes
SSLmode=Require
ConnSettings=
Paramètre Description
ReadOnly Indique si la connexion à la base de données autorise uniquement les opérations de lecture (requêtes SELECT) et limite les modifications (instructions INSERT, UPDATE et DELETE) ; utile dans les scénarios où les données doivent rester inchangées.
Protocol Version du protocole backend PostgreSQL (ignorée lors de l’utilisation de connexions SSL).
ShowOidColumn Indique s’il faut inclure l’Object ID (OID) dans SQLColumns.
FakeOidIndex Indique s’il faut créer un faux index unique sur l’OID.
RowVersioning Indique s’il faut permettre aux applications de détecter si des données ont été modifiées par d’autres utilisateurs pendant que vous tentez de mettre à jour une ligne. Notez que ce paramètre peut accélérer le processus de mise à jour, car, pour mettre à jour une ligne, il n’est pas nécessaire de spécifier chaque colonne individuellement dans la clause WHERE.
ShowSystemTables Indique si le pilote de base de données doit traiter les tables système comme des tables ordinaires dans SQLTables ; utile pour l’accessibilité, en permettant la visibilité sur les tables système.
Fetch Indique si le pilote doit utiliser automatiquement declare cursor/fetch pour gérer les instructions SELECT et maintenir un cache de 100 lignes.
BoolsAsChar Contrôle le mappage des types booléens.
S’il est défini sur "Yes", les booléens sont mappés sur SQL_CHAR ; sinon, ils sont mappés sur SQL_BIT.
SSLmode Indique le mode SSL pour la connexion.
ConnSettings Paramètres supplémentaires envoyés au backend lors de la connexion.
Test de la connexion ODBC

Pour vérifier si la connexion ODBC fonctionne correctement, vous pouvez utiliser l’utilitaire isql (inclus dans le paquet unixODBC) :

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

Configuration d’un élément dans l’interface web Zabbix

Configurez un item de surveillance de base de données.

Tous les champs de saisie obligatoires sont marqués d’un astérisque rouge.

Pour les éléments de surveillance de base de données, vous devez spécifier :
Type Sélectionnez « Database monitor » ici.
Key Saisissez l’une des clés d’élément prises en charge :
db.odbc.select[] - cet élément renvoie une valeur (la première colonne de la première ligne du résultat de la requête SQL) ;
db.odbc.get[] - cet élément renvoie plusieurs lignes/colonnes au format JSON ;
db.odbc.discovery[] - cet élément renvoie des données de découverte de bas niveau.
User name Saisissez le nom d’utilisateur de la base de données (jusqu’à 255 caractères).
Ce paramètre est facultatif si le nom d’utilisateur de la base de données est spécifié dans le fichier odbc.ini.
Si une chaîne de connexion est utilisée et que le champ User name n’est pas vide, il est alors ajouté à la chaîne de connexion sous la forme UID=<user>.
Password Saisissez le mot de passe de l’utilisateur de la base de données (jusqu’à 255 caractères).
Ce paramètre est facultatif si le mot de passe est spécifié dans le fichier odbc.ini.
Si une chaîne de connexion est utilisée et que le champ Password n’est pas vide, il est alors ajouté à la chaîne de connexion sous la forme PWD=<password>.
Les caractères spéciaux sont pris en charge dans ce champ.
Le mot de passe sera ajouté à la chaîne de connexion après le nom d’utilisateur, par exemple UID=<username>;PWD=P?;)*word.
Pour tester la chaîne résultante, vous pouvez exécuter la commande suivante :
isql -v -k 'Driver=libmaodbc.so;Database=zabbix;UID=zabbix;PWD=P?;)*word'
SQL query Saisissez la requête SQL.
Notez qu’avec db.odbc.select[], la requête ne doit renvoyer qu’une seule valeur.
Type of information Sélectionnez ici le type d’information qui sera renvoyé par la requête.
Si le type d’information est sélectionné de manière incorrecte, l’élément deviendra non pris en charge.

Remarques importantes

  • Les éléments de surveillance de base de données deviendront non pris en charge si aucun processus odbc poller n’est démarré dans la configuration du serveur ou du proxy. Pour activer les pollers ODBC, définissez le paramètre StartODBCPollers dans le fichier de configuration du server Zabbix ou, pour les vérifications effectuées par le proxy, dans le fichier de configuration du proxy Zabbix.
  • La valeur du paramètre Timeout dans le formulaire de configuration de l’élément est utilisée comme délai d’expiration de connexion ODBC et comme délai d’expiration d’exécution de la requête. Notez que ces paramètres de délai d’expiration peuvent être ignorés si le pilote ODBC installé ne les prend pas en charge.
  • La commande SQL doit renvoyer un ensemble de résultats comme toute requête utilisant l’instruction select. La syntaxe de la requête dépend du SGBDR qui la traitera. La syntaxe d’une requête vers une procédure stockée doit commencer par le mot-clé call.

Détails de la clé d’élément

Les paramètres sans chevrons sont obligatoires. Les paramètres marqués par des chevrons < > sont facultatifs.

db.odbc.select[<description courte unique>,<dsn>,<chaîne de connexion>]


Renvoie une valeur, c’est-à-dire la première colonne de la première ligne du résultat de la requête SQL.
Valeur de retour : selon la requête SQL.

Paramètres :

  • description courte unique - une description courte unique permettant d’identifier l’élément (à utiliser dans les déclencheurs, etc.) ;
  • dsn - le nom de la source de données (tel que spécifié dans odbc.ini) ;
  • chaîne de connexion - la chaîne de connexion (peut contenir des arguments spécifiques au pilote).

Commentaires :

  • Bien que dsn et chaîne de connexion soient des paramètres facultatifs, au moins l’un des deux est requis ; si les deux sont définis, dsn sera ignoré.
  • Si une requête renvoie plus d’une colonne, seule la première colonne est lue. Si une requête renvoie plus d’une ligne, seule la première ligne est lue.
db.odbc.get[<description courte unique>,<dsn>,<chaîne de connexion>]


Transforme le résultat de la requête SQL en un tableau JSON.
Valeur de retour : objet JSON.

Paramètres :

  • description courte unique - une description courte unique permettant d’identifier l’élément (à utiliser dans les déclencheurs, etc.) ;
  • dsn - le nom de la source de données (tel que spécifié dans odbc.ini) ;
  • chaîne de connexion - la chaîne de connexion (peut contenir des arguments spécifiques au pilote).

Commentaires :

  • Bien que dsn et chaîne de connexion soient des paramètres facultatifs, au moins l’un des deux est requis ; si les deux sont définis, dsn sera ignoré.
  • Plusieurs lignes/colonnes au format JSON peuvent être renvoyées. Cet élément peut être utilisé comme élément maître collectant toutes les données en un seul appel système, tandis que le prétraitement JSONPath peut être utilisé dans les éléments dépendants pour extraire des valeurs individuelles. Pour plus d’informations, consultez un exemple du format renvoyé, utilisé dans la découverte de bas niveau.

Exemple :

# Connexion pour le pilote ODBC MySQL 5 :
db.odbc.get[MySQL example,,"Driver=/usr/local/lib/libmyodbc5a.so;Database=master;Server=127.0.0.1;Port=3306"]
db.odbc.discovery[<description courte unique>,<dsn>,<chaîne de connexion>]


Transforme le résultat de la requête SQL en un tableau JSON, utilisé pour la découverte de bas niveau. Les noms de colonnes du résultat de la requête sont convertis en noms de macros de découverte de bas niveau, associés aux valeurs des champs découverts. Ces macros peuvent être utilisées lors de la création de prototypes d'éléments, de déclencheurs, etc.
Valeur de retour : objet JSON.

Paramètres :

  • description courte unique - une description courte unique permettant d'identifier l'élément (à utiliser dans les déclencheurs, etc.) ;
  • dsn - le nom de la source de données (tel que spécifié dans odbc.ini) ;
  • chaîne de connexion - la chaîne de connexion (peut contenir des arguments spécifiques au pilote).

Commentaires :

  • Bien que dsn et chaîne de connexion soient des paramètres facultatifs, au moins l'un des deux est requis ; si les deux sont définis, dsn sera ignoré.

Messages d'erreur

Les messages d'erreur ODBC sont structurés en champs afin de fournir des informations détaillées. Par exemple, un message d'erreur peut ressembler à ceci :

Cannot execute ODBC query: [SQL_ERROR]:[42601][7][ERROR: syntax error at or near ";"; Error while executing the query]
  • "Cannot execute ODBC query" - message Zabbix
  • "[SQL_ERROR]" - code de retour ODBC
  • "[42601]" - SQLState
  • "[7]" - code d'erreur natif
  • "[ERROR: syntax error at or near ";"; Error while executing the query]" - message d'erreur natif

Notez que la longueur du message d'erreur est limitée à 2048 octets ; le message peut donc être tronqué. S'il y a plus d'un enregistrement de diagnostic ODBC, Zabbix essaie de les concaténer (séparés par |) dans la mesure permise par la limite de longueur.