Este guia aborda a configuração das versões suportadas do ClickHouse. Se você estiver usando uma versão diferente, algumas funcionalidades podem não funcionar como esperado.

O ClickHouse pode armazenar os seguintes tipos de valor:

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

O ClickHouse não aceita arrays JSON. Um valor JSON deve ser um único objeto ou um conjunto de objetos. Além disso, o ClickHouse trata chaves JSON com NULL da mesma forma que chaves ausentes.

Notas importantes

O housekeeper não exclui dados do ClickHouse. Para controlar por quanto tempo os dados são mantidos, configure o período de armazenamento de dados do ClickHouse no ClickHouse.
O Zabbix não calcula nem armazena trends no ClickHouse. Considere estender o período de armazenamento do histórico para preservar dados mais antigos.
Se você quiser migrar seus dados de histórico de um banco de dados Zabbix existente (MySQL ou PostgreSQL) para o ClickHouse, consulte os scripts de migração do esquema e do histórico do ClickHouse.
O ClickHouse não é suportado para proxies do Zabbix.

Configurando o ClickHouse

Você precisa criar e configurar um banco de dados e um usuário do Zabbix, além de importar o esquema do banco de dados.

Este guia fornece instruções para instalações do ClickHouse via Docker ou pacote.

Docker

1. Crie e configure o banco de dados e o usuário do Zabbix ao executar o container do 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 o ClickHouse está funcionando e que você consegue se conectar a ele:

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

# 26.4.4.38

3. Importe o esquema do banco de dados usando o script history_all.sh do seu diretório do Zabbix:

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

O período de armazenamento dos dados (Time-To-Live, ou TTL) para o ClickHouse é, por padrão, de 31 dias. Para alterá-lo, use a opção --ttl ao importar o esquema do banco de dados (por exemplo, --ttl 604800 para 7 dias) ou configure isso depois.

4. Verifique se as tabelas foram criadas:

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

Pacotes

1. Inicie o ClickHouse:

sudo service clickhouse-server start

2. Crie e configure o banco de dados e o usuário do 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 o schema do banco de dados usando o script history_all.sh do seu diretório do Zabbix:

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

O período de armazenamento dos dados (Time-To-Live, ou TTL) para o ClickHouse é, por padrão, de 31 dias. Para alterá-lo, use a opção --ttl ao importar o schema do banco de dados (por exemplo, --ttl 604800 para 7 dias) ou configure isso posteriormente.

4. Verifique se as tabelas foram criadas:

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

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

Configurando o Zabbix server

No arquivo de configuração do Zabbix server (zabbix_server.conf), defina o parâmetro HistoryProvider.

Por exemplo, para armazenar todos os tipos de valores suportados no ClickHouse:

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

Após fazer as alterações, reinicie o Zabbix server:

systemctl restart zabbix-server

Configurando o frontend do Zabbix

No arquivo de configuração do frontend do Zabbix (zabbix.conf.php), defina a variável $HISTORY_PROVIDERS para corresponder à configuração do server:

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

Configuração adicional

As etapas abaixo são opcionais. Você não precisa delas para uma configuração básica.

Configurando o período de armazenamento de dados do ClickHouse

O período de armazenamento de dados (Time-To-Live, ou TTL) do ClickHouse é, por padrão, de 31 dias. Para alterá-lo, execute os comandos abaixo.

Os exemplos abaixo usam Docker. Se você instalou o ClickHouse usando pacotes, execute as consultas diretamente no cliente do ClickHouse.

1. Altere a tabela (substitua history_json e 3600 pelos valores necessários):

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 as alterações imediatamente:

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

3. Verifique se o período de armazenamento de dados foi alterado:

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 o Zabbix server para atualizar o período de armazenamento de dados em Administration > 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

Solução de problemas

As etapas a seguir podem ajudar você a solucionar problemas com sua configuração do ClickHouse:

Verifique os logs do ClickHouse ou do server do Zabbix em busca de erros.
Para identificar consultas lentas, use a opção log_slow_queries no parâmetro de configuração do server do Zabbix HistoryProvider.
Verifique se o ClickHouse permite acesso a partir do server do Zabbix e do frontend do Zabbix.
Consulte o ClickHouse para ver se os dados coletados pelo Zabbix estão armazenados, por exemplo:

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 da distribuição sobre a configuração do Nginx para o Zabbix

Docs

Configuração do ClickHouse