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 o esquema do ClickHouse e os scripts de migração do histórico.
O ClickHouse não é suportado para proxies do Zabbix.
Se você tiver um cluster ClickHouse, consulte Configurando clusters do ClickHouse.

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

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

Configurando clusters do ClickHouse

Esta seção fornece etapas de configuração para clusters do ClickHouse com replicação e sharding.

As etapas abaixo usam Docker e o ClickHouse cluster_2S_2R da documentação do ClickHouse (executando ClickHouse 26.4.4.38 com ClickHouse Keeper).

Antes de começar, é recomendável colocar um balanceador de carga na frente do seu cluster do ClickHouse para o Zabbix. A configuração do server e do frontend do Zabbix suporta apenas uma única URL do ClickHouse, então ela só pode apontar para um nó. Se esse nó ficar indisponível, um balanceador de carga redirecionará o Zabbix para um nó saudável, usando a mesma URL.

1. Crie o banco de dados do 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}')"

A cláusula ON CLUSTER alcança apenas os nós que fazem parte do cluster no momento em que você executa o comando. Se você adicionar nós ao cluster mais tarde, execute este comando novamente.

2. Crie e configure o usuário do 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 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 \
  --engine "ReplicatedMergeTree()"

O período de retenção 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 mais tarde.

Se o seu cluster do ClickHouse exigir caminhos explícitos para réplicas (por exemplo, se a configuração do seu server do ClickHouse não definir caminhos padrão para tabelas replicadas), execute os scripts de esquema (history_schema.sh, history_uint_schema.sh, etc.) individualmente e defina um caminho diferente para cada tabela:

./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 mais detalhes sobre replicação no ClickHouse, consulte Replicating data e Replicated* table engines na documentação do ClickHouse.

4. Configure o sharding para cada tipo de tabela. Renomeie as tabelas e crie uma tabela Distributed com o nome original, apontando para a tabela renomeada. Essa tabela Distributed é a partir da qual o Zabbix realmente lê e grava; a tabela divide os dados automaticamente entre os shards. Por exemplo, para a tabela 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 mais detalhes sobre sharding no ClickHouse, consulte Distributed table engine na documentação do ClickHouse.

5. Configure o server do Zabbix.

6. Configure o frontend do Zabbix.

7. Verifique se os dados do Zabbix estão distribuídos entre os shards. A contagem de linhas em zabbix.history_local pode mudar entre verificações repetidas, já que o server do Zabbix insere novos dados continuamente. Execute este comando em cada nó:

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. Verifique se a replicação está sincronizada (active_replicas deve corresponder a 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