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 history para preservar dados mais antigos.
Se você quiser migrar seus dados de history de um banco de dados Zabbix existente (MySQL ou PostgreSQL) para o ClickHouse, consulte o esquema do ClickHouse e os scripts de migração de history.
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

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