Ce guide couvre la configuration des versions prises en charge de ClickHouse. Si vous utilisez une version différente, certaines fonctionnalités risquent de ne pas fonctionner comme prévu.

ClickHouse peut stocker les types de valeurs suivants :

Item value type	Database table	ClickHouse type
Numeric (unsigned)	history_uint	uint
Numeric (float)	history	dbl
Character	history_str	str
Log	history_log	log
Text	history_text	text
Binary	history_bin	not supported by Zabbix
JSON	history_json	json

ClickHouse n'accepte pas les tableaux JSON. Une valeur JSON doit être soit un objet unique, soit un ensemble d'objets. De plus, ClickHouse gère les clés JSON avec NULL de la même manière que les clés manquantes.

Notes importantes

Le housekeeper ne supprime pas les données de ClickHouse. Pour contrôler la durée de conservation des données, configurez la période de stockage des données ClickHouse dans ClickHouse.
Zabbix ne calcule ni ne stocke les tendances dans ClickHouse. Envisagez d'allonger la période de stockage de l'historique afin de conserver les données plus anciennes.
Si vous souhaitez migrer vos données d'historique depuis une base de données Zabbix existante (MySQL ou PostgreSQL) vers ClickHouse, consultez les schémas ClickHouse et les scripts de migration de l'historique.
ClickHouse n'est pas pris en charge pour les proxies Zabbix.
Si vous disposez d'un cluster ClickHouse, consultez Configuration des clusters ClickHouse.

Configuration de ClickHouse

Vous devez créer et configurer une base de données Zabbix et un utilisateur, puis importer le schéma de la base de données.

Ce guide fournit des instructions pour les installations de ClickHouse via Docker ou via package.

Docker

1. Créez et configurez la base de données et l'utilisateur Zabbix lors de l'exécution du conteneur ClickHouse :

sudo docker run -d \
  --name clickhouse \
  -e CLICKHOUSE_DB=zabbix \
  -e CLICKHOUSE_USER=zabbix \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  -e CLICKHOUSE_PASSWORD=<password> \
  -p 8123:8123/tcp \
  -p 9000:9000/tcp \
  --cap-add=SYS_NICE \
  --cap-add=NET_ADMIN \
  --cap-add=IPC_LOCK \
  --ulimit nofile=262144:262144 \
  -v clickhouse_data:/var/lib/clickhouse \
  clickhouse/clickhouse-server:26.4

2. Vérifiez que ClickHouse fonctionne et que vous pouvez vous y connecter :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --query "SELECT version()"

# 26.4.4.38

3. Importez le schéma de la base de données à l'aide du script history_all.sh depuis votre répertoire Zabbix :

./usr/share/zabbix/sql-scripts/clickhouse/history_all.sh \
  --user zabbix \
  --password <password> \
  --db zabbix \
  --server http://localhost:8123

La période de conservation des données (Time-To-Live, ou TTL) pour ClickHouse est, par défaut, de 31 jours. Pour la modifier, utilisez l'option --ttl lors de l'import du schéma de la base de données (par exemple, --ttl 604800 pour 7 jours), ou configurez-la ultérieurement.

4. Vérifiez que les tables ont été créées :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "SHOW TABLES FROM zabbix"

# history
# history_json
# history_log
# history_str
# history_text
# history_uint

Packages

1. Démarrez ClickHouse :

sudo service clickhouse-server start

2. Créez et configurez la base de données et l'utilisateur Zabbix :

clickhouse-client --user default

localhost :) CREATE DATABASE IF NOT EXISTS zabbix
localhost :) CREATE USER IF NOT EXISTS zabbix IDENTIFIED WITH sha256_password BY '<password>'
localhost :) GRANT CREATE, ALTER, DROP, INSERT, SELECT, UPDATE, OPTIMIZE ON zabbix.* TO zabbix
localhost :) quit

3. Importez le schéma de la base de données à l'aide du script history_all.sh depuis votre répertoire Zabbix :

./usr/share/zabbix/sql-scripts/clickhouse/history_all.sh \
  --user zabbix \
  --password <password> \
  --db zabbix \
  --server http://localhost:8123

4. Vérifiez que les tables ont été créées :

clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "SHOW TABLES FROM zabbix"

# history
# history_json
# history_log
# history_str
# history_text
# history_uint

Configuration du serveur Zabbix

Dans le fichier de configuration de votre serveur Zabbix (zabbix_server.conf), définissez le paramètre HistoryProvider.

Par exemple, pour stocker tous les types de valeurs pris en charge dans ClickHouse :

HistoryProvider=clickhouse;value_types="uint,dbl,str,log,text,json",url=http://localhost:8123,db=zabbix,username=zabbix,password=<password>

Après avoir effectué les modifications, redémarrez le serveur Zabbix :

systemctl restart zabbix-server

Configuration de l'interface Zabbix

Dans votre fichier de configuration de l'interface Zabbix (zabbix.conf.php), définissez la variable $HISTORY_PROVIDERS de manière à correspondre à la configuration du serveur :

$HISTORY_PROVIDERS[] = [
  'types' => ['uint','dbl','str','log','text','json'],
  'provider' => 'clickhouse',
  'url' => 'http://localhost:8123',
  'db' => 'zabbix',
  'username' => 'zabbix',
  'password' => '<password>'
];

Configuration supplémentaire

Les étapes ci-dessous sont facultatives. Vous n'en avez pas besoin pour une configuration de base.

Configuration de la période de conservation des données ClickHouse

La période de conservation des données (Time-To-Live, ou TTL) pour ClickHouse est, par défaut, de 31 jours. Pour la modifier, exécutez les commandes ci-dessous.

Les exemples ci-dessous utilisent Docker. Si vous avez installé ClickHouse à l'aide de paquets, exécutez les requêtes directement dans le client ClickHouse.

1. Modifiez la table (remplacez history_json et 3600 par les valeurs dont vous avez besoin) :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "ALTER TABLE zabbix.history_json MODIFY TTL clock_ns + toIntervalSecond(3600)"

2. Appliquez immédiatement les modifications :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "OPTIMIZE TABLE zabbix.history_json MATERIALIZE TTL"

3. Vérifiez que la période de conservation des données a changé :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "SHOW CREATE TABLE zabbix.history_json"

# CREATE TABLE zabbix.history_json
# (
#     `itemid` UInt64,
#     `clock_ns` DateTime64(9),
#     `value` JSON,
#     `value_str` String
# )
# ENGINE = MergeTree
# PARTITION BY toDate(clock_ns)
# PRIMARY KEY (itemid, clock_ns)
# ORDER BY (itemid, clock_ns)
# TTL clock_ns + toIntervalSecond(3600)
# SETTINGS index_granularity = 8192

4. Redémarrez le serveur Zabbix pour actualiser la période de conservation des données dans Administration > Housekeeping :

systemctl restart zabbix-server

Configuration des clusters ClickHouse

Cette section fournit les étapes de configuration des clusters ClickHouse avec réplication et sharding.

Les étapes ci-dessous utilisent Docker et le ClickHouse cluster_2S_2R de la documentation ClickHouse (exécutant ClickHouse 26.4.4.38 avec ClickHouse Keeper).

Avant de commencer, il est recommandé de placer un équilibreur de charge devant votre cluster ClickHouse pour Zabbix. La configuration du serveur Zabbix et de l'interface ne prend en charge qu'une seule URL ClickHouse, elle ne peut donc pointer que vers un seul noeud. Si ce noeud tombe en panne, un équilibreur de charge redirigera Zabbix vers un noeud sain à la place, via cette même URL.

1. Créez la base de données Zabbix :

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "CREATE DATABASE IF NOT EXISTS zabbix ON CLUSTER cluster_2S_2R ENGINE = Replicated('/clickhouse/databases/zabbix', '{shard}', '{replica}')"

La clause ON CLUSTER n'atteint que les noeuds qui font partie du cluster au moment où vous exécutez la commande. Si vous ajoutez des noeuds à votre cluster ultérieurement, exécutez cette commande à nouveau.

2. Créez et configurez l'utilisateur Zabbix :

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "CREATE USER IF NOT EXISTS zabbix ON CLUSTER cluster_2S_2R IDENTIFIED WITH sha256_password BY '<password>'"

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "GRANT ON CLUSTER cluster_2S_2R CREATE, ALTER, DROP, INSERT, SELECT, UPDATE, OPTIMIZE ON zabbix.* TO zabbix"

3. Importez le schéma de base de données à l'aide du script history_all.sh depuis votre répertoire Zabbix :

./usr/share/zabbix/sql-scripts/clickhouse/history_all.sh \
  --user zabbix \
  --password <password> \
  --db zabbix \
  --server http://localhost:8123 \
  --engine "ReplicatedMergeTree()"

La période de conservation des données (Time-To-Live, ou TTL) pour ClickHouse est, par défaut, de 31 jours. Pour la modifier, utilisez l'option --ttl lors de l'import du schéma de base de données (par exemple, --ttl 604800 pour 7 jours), ou configurez la plus tard.

Si votre cluster ClickHouse nécessite des chemins de réplique explicites (par exemple, si la configuration de votre serveur ClickHouse ne définit pas de chemins par défaut pour les tables répliquées), exécutez les scripts de schéma (history_schema.sh, history_uint_schema.sh, etc.) individuellement et définissez un chemin différent pour chaque table :

./usr/share/zabbix/sql-scripts/clickhouse/history_schema.sh \
  --user zabbix \
  --password <password> \
  --db zabbix \
  --server http://localhost:8123 \
  --engine "ReplicatedMergeTree('/clickhouse/tables/{shard}/history', '{replica}')"

Pour plus de détails sur la réplication ClickHouse, consultez Replicating data et Replicated* table engines dans la documentation ClickHouse.

4. Configurez le sharding pour chaque type de table. Renommez les tables et créez une table Distributed avec le nom d'origine, pointant vers la table renommée. Cette table Distributed est celle que Zabbix lit et écrit réellement ; la table répartit automatiquement les données entre les shards. Par exemple, pour la table history :

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "RENAME TABLE zabbix.history TO zabbix.history_local"

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "CREATE TABLE zabbix.history AS zabbix.history_local ENGINE = Distributed('cluster_2S_2R', 'zabbix', 'history_local', itemid)"

Pour plus de détails sur le sharding ClickHouse, consultez Distributed table engine dans la documentation ClickHouse.

5. Configurez le serveur Zabbix.

6. Configurez l'interface Zabbix.

7. Vérifiez que les données Zabbix sont réparties entre les shards. Le nombre de lignes de zabbix.history_local peut changer entre deux vérifications, car le serveur Zabbix insère continuellement de nouvelles données. Exécutez cette commande sur chaque noeud :

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "SELECT count(*) FROM zabbix.history_local"

# 2446 (clickhouse-01)
# 2471 (clickhouse-02)
# 2494 (clickhouse-03)

8. Vérifiez que la réplication est synchronisée (active_replicas doit correspondre à total_replicas) :

sudo docker exec -it clickhouse-01 \
  clickhouse-client \
  --user default \
  --query "SELECT database, table, is_leader, total_replicas, active_replicas FROM system.replicas WHERE database = 'zabbix'"

# zabbix  history_json_local  1 2 2
# zabbix  history_local       1 2 2
# zabbix  history_log_local   1 2 2
# zabbix  history_str_local   1 2 2
# zabbix  history_text_local  1 2 2
# zabbix  history_uint_local  1 2 2

Dépannage

Les étapes suivantes peuvent vous aider à résoudre les problèmes liés à votre configuration ClickHouse :

Vérifiez les journaux de ClickHouse ou du serveur Zabbix pour détecter des erreurs.
Pour identifier les requêtes lentes, utilisez l'option log_slow_queries dans le paramètre de configuration du serveur Zabbix HistoryProvider.
Vérifiez que ClickHouse autorise l'accès depuis le serveur Zabbix et l'interface Zabbix.
Interrogez ClickHouse pour vérifier si les données collectées par Zabbix sont stockées, par exemple :

sudo docker exec -it clickhouse \
  clickhouse-client \
  --user zabbix \
  --password <password> \
  --query "SELECT * FROM zabbix.history_uint WHERE itemid = 42269"

What’s next?

Notes spécifiques à la distribution sur la configuration de Nginx pour Zabbix

Docs

Configuration de ClickHouse

Notes importantes

Configuration de ClickHouse

Docker

Packages

Configuration du serveur Zabbix

Configuration de l'interface Zabbix

Configuration supplémentaire

Configuration de la période de conservation des données ClickHouse

Configuration des clusters ClickHouse

Dépannage

What’s next?

Suggest edit

Suggest an example

Thank you!