Esta guía cubre la configuración para las versiones compatibles de ClickHouse. Si está usando una versión diferente, es posible que algunas funciones no funcionen como se espera.

ClickHouse puede almacenar los siguientes tipos de valores:

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 no acepta matrices JSON. Un valor JSON debe ser un único objeto o un conjunto de objetos. Además, ClickHouse gestiona las claves JSON con NULL igual que las claves ausentes.

Notas importantes

El housekeeper no elimina datos de ClickHouse. Para controlar durante cuánto tiempo se conservan los datos, configure el período de almacenamiento de datos de ClickHouse en ClickHouse.
Zabbix no calcula ni almacena tendencias en ClickHouse. Considere ampliar el período de almacenamiento del historial para conservar datos más antiguos.
Si desea migrar los datos del historial desde una base de datos de Zabbix existente (MySQL o PostgreSQL) a ClickHouse, consulte los scripts de migración del esquema de ClickHouse y del historial.
ClickHouse no es compatible con los proxies de Zabbix.

Configuración de ClickHouse

Debe crear y configurar una base de datos y un usuario de Zabbix, e importar el esquema de la base de datos.

Esta guía proporciona instrucciones para instalaciones de ClickHouse mediante Docker o paquetes.

Docker

1. Cree y configure la base de datos y el usuario de Zabbix al ejecutar el contenedor de 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. Confirme que ClickHouse funciona y que puede conectarse a él:

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

# 26.4.4.38

3. Importe el esquema de la base de datos usando el script history_all.sh desde su directorio de Zabbix:

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

El período de almacenamiento de datos (Time-To-Live, o TTL) para ClickHouse es, de forma predeterminada, de 31 días. Para cambiarlo, use la opción --ttl al importar el esquema de la base de datos (por ejemplo, --ttl 604800 para 7 días), o configúrelo más adelante.

4. Verifique que se hayan creado las tablas:

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

Paquetes

1. Inicie ClickHouse:

sudo service clickhouse-server start

2. Cree y configure la base de datos y el usuario de 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. Importe el esquema de la base de datos usando el script history_all.sh desde su directorio de Zabbix:

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

4. Verifique que se hayan creado las tablas:

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

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

Configuración de Zabbix server

En el archivo de configuración de Zabbix server (zabbix_server.conf), establezca el parámetro HistoryProvider.

Por ejemplo, para almacenar todos los tipos de valores admitidos en ClickHouse:

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

Después de realizar los cambios, reinicie Zabbix server:

systemctl restart zabbix-server

Configuración del frontend de Zabbix

En el archivo de configuración de tu frontend de Zabbix (zabbix.conf.php), establece la variable $HISTORY_PROVIDERS para que coincida con la configuración del server:

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

Configuración adicional

Los pasos siguientes son opcionales. No los necesita para una configuración básica.

Configuración del período de almacenamiento de datos de ClickHouse

El período de almacenamiento de datos (Time-To-Live, o TTL) de ClickHouse es, de forma predeterminada, de 31 días. Para cambiarlo, ejecute los comandos siguientes.

Los ejemplos siguientes usan Docker. Si instaló ClickHouse mediante paquetes, ejecute las consultas directamente en el cliente de ClickHouse.

1. Modifique la tabla (reemplace history_json y 3600 por los valores que necesite):

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

2. Aplique los cambios inmediatamente:

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

3. Verifique que el período de almacenamiento de datos haya cambiado:

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. Reinicie Zabbix server para actualizar el período de almacenamiento de datos en Administración > Housekeeping:

systemctl restart zabbix-server

Configuring ClickHouse clusters

This section provides configuration steps for ClickHouse clusters with replication and sharding.

The steps below use Docker and the ClickHouse cluster_2S_2R from ClickHouse documentation (running ClickHouse 26.4.4.38 with ClickHouse Keeper).

Before you start, it is recommended to put a load balancer in front of your ClickHouse cluster for Zabbix. Zabbix server and frontend configuration supports only a single ClickHouse URL, so it can only point to one node. If that node goes down, a load balancer will redirect Zabbix to a healthy node instead, through that same URL.

1. Create the Zabbix database:

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}')"

The ON CLUSTER clause reaches only nodes that are part of the cluster when you run the command. If you add nodes to your cluster later, run this command again.

2. Create and configure the Zabbix user:

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. Import the database schema using the history_all.sh script from your Zabbix directory:

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

The data storage period (Time-To-Live, or TTL) for ClickHouse is, by default, 31 days. To change it, use the --ttl option when importing the database schema (e.g., --ttl 604800 for 7 days), or configure it later.

If your ClickHouse cluster requires explicit replica paths (for example, if your ClickHouse server configuration does not set default paths for replicated tables), run the schema scripts (history_schema.sh, history_uint_schema.sh, etc.) individually and set a different path for each 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}')"

For more details on ClickHouse replication, see Replicating data and Replicated* table engines in ClickHouse documentation.

4. Configure sharding for each table type. Rename the tables and create a Distributed table with the original name, pointing to the renamed table. This Distributed table is what Zabbix actually reads from and writes to; the table splits data across shards automatically. For example, for the history table:

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)"

For more details on ClickHouse sharding, see Distributed table engine in ClickHouse documentation.

5. Configure Zabbix server.

6. Configure Zabbix frontend.

7. Verify that Zabbix data is spread across shards. The row count from zabbix.history_local may change between repeated checks, since Zabbix server continuously inserts new data. Run this command on each node:

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. Check that replication is in sync (active_replicas should match 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

Solución de problemas

Los siguientes pasos pueden ayudarle a solucionar problemas con su configuración de ClickHouse:

Revise los registros de ClickHouse o del server de Zabbix en busca de errores.
Para identificar consultas lentas, use la opción log_slow_queries en el parámetro de configuración del server de Zabbix HistoryProvider.
Verifique que ClickHouse permita el acceso desde el server de Zabbix y el frontend de Zabbix.
Consulte ClickHouse para ver si los datos recopilados por Zabbix se almacenan, por ejemplo:

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

What’s next?

Notas específicas de la distribución sobre la configuración de Nginx para Zabbix

Docs

Configuración de ClickHouse

Notas importantes

Configuración de ClickHouse

Docker

Paquetes

Configuración de Zabbix server

Configuración del frontend de Zabbix

Configuración adicional

Configuración del período de almacenamiento de datos de ClickHouse

Configuring ClickHouse clusters

Solución de problemas

What’s next?

Suggest edit

Suggest an example

Thank you!