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 el esquema de ClickHouse y los scripts de migración del historial.
ClickHouse no es compatible con los proxies de Zabbix.
Si tiene un clúster de ClickHouse, consulte Configuración de clústeres de ClickHouse.

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 MATERIALIZE TTL"

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

Configuración de clústeres de ClickHouse

Esta sección proporciona los pasos de configuración para clústeres de ClickHouse con replicación y particionado.

Los pasos siguientes usan Docker y el ClickHouse cluster_2S_2R de la documentación de ClickHouse (ejecutando ClickHouse 26.4.4.38 con ClickHouse Keeper).

Antes de empezar, se recomienda colocar un balanceador de carga delante de su clúster de ClickHouse para Zabbix. La configuración de Zabbix server y frontend solo admite una única URL de ClickHouse, por lo que solo puede apuntar a un nodo. Si ese nodo deja de funcionar, un balanceador de carga redirigirá Zabbix a un nodo sano en su lugar, a través de esa misma URL.

1. Cree la base de datos de 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 cláusula ON CLUSTER alcanza solo a los nodos que forman parte del clúster cuando ejecuta el comando. Si añade nodos a su clúster más adelante, ejecute este comando de nuevo.

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

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

Si su clúster de ClickHouse requiere rutas explícitas para las réplicas (por ejemplo, si la configuración de su servidor ClickHouse no establece rutas predeterminadas para tablas replicadas), ejecute los scripts de esquema (history_schema.sh, history_uint_schema.sh, etc.) de forma individual y establezca una ruta diferente para cada tabla:

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

Para obtener más detalles sobre la replicación en ClickHouse, consulte Replicating data y Replicated* table engines en la documentación de ClickHouse.

4. Configure el sharding para cada tipo de tabla. Cambie el nombre de las tablas y cree una tabla Distributed con el nombre original, apuntando a la tabla renombrada. Esta tabla Distributed es la que Zabbix realmente lee y escribe; la tabla divide los datos entre shards automáticamente. Por ejemplo, para la tabla 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)"

Para obtener más detalles sobre el sharding en ClickHouse, consulte Distributed table engine en la documentación de ClickHouse.

5. Configure Zabbix server.

6. Configure Zabbix frontend.

7. Verifique que los datos de Zabbix estén distribuidos entre los shards. El recuento de filas de zabbix.history_local puede cambiar entre comprobaciones repetidas, ya que Zabbix server inserta continuamente nuevos datos. Ejecute este comando en cada nodo:

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. Compruebe que la replicación esté sincronizada (active_replicas debe coincidir con 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

Configuración de clústeres de ClickHouse

Solución de problemas

What’s next?

Suggest edit

Suggest an example

Thank you!