ClickHouseのセットアップ

Zabbixは、リレーショナルデータベースの代替として、ClickHouse に履歴データを保存できます。

このガイドでは、ClickHouseのサポート対象バージョンのセットアップについて説明します。
別のバージョンを使用している場合、一部の機能が想定どおりに動作しないことがあります。

ClickHouseは、次の値タイプを保存できます。

重要な注意事項

• housekeeper は ClickHouse からデータを削除しません。 データの保持期間を制御するには、ClickHouse で ClickHouse のデータ保存期間を設定 してください。
• Zabbix は ClickHouse でトレンドを計算または保存しません。 古いデータを保持するには、履歴保存期間 を延長することを検討してください。
• 既存の Zabbix データベース (MySQL または PostgreSQL) から ClickHouse に履歴データを移行したい場合は、ClickHouse スキーマと履歴の migration scripts を参照してください。
• ClickHouse は Zabbix プロキシではサポートされていません。
• ClickHouse クラスターを使用している場合は、ClickHouse クラスターの設定 を参照してください。

ClickHouseの設定

Zabbixのデータベースとユーザーを作成して設定し、データベーススキーマをインポートする必要があります。

このガイドでは、ClickHouseのDockerまたはパッケージによるインストール手順を説明します。

Docker

1. ClickHouse コンテナを実行する際に、Zabbix データベースとユーザーを作成および設定します:

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. ClickHouse が動作しており、接続できることを確認します:

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

# 26.4.4.38

3. Zabbix ディレクトリにある history_all.sh スクリプトを使用して、データベーススキーマをインポートします:

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

4. テーブルが作成されたことを確認します:

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

パッケージ

1. ClickHouseを起動します:

sudo service clickhouse-server start

2. 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. Zabbixディレクトリにあるhistory_all.shスクリプトを使用して、データベーススキーマをインポートします:

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

4. テーブルが作成されたことを確認します:

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

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

Zabbixサーバーの設定

Zabbixサーバーの設定ファイル (zabbix_server.conf) で、HistoryProvider パラメーターを設定します。

たとえば、ClickHouse にサポートされているすべての値のタイプを保存するには、次のようにします。

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

変更を行った後、Zabbixサーバーを再起動します。

systemctl restart zabbix-server

Zabbix Webインターフェースの設定

Zabbix Webインターフェースの設定ファイル (zabbix.conf.php) で、サーバーの設定に合わせて $HISTORY_PROVIDERS 変数を設定します。

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

追加設定

以下の手順は任意です。 基本的なセットアップでは必要ありません。

ClickHouseのデータ保存期間の設定

ClickHouseのデータ保存期間（Time-To-Live、TTL）は、デフォルトで31日です。
変更するには、以下のコマンドを実行します。

以下の例ではDockerを使用しています。
ClickHouseをパッケージでインストールした場合は、ClickHouseクライアントでクエリを直接実行してください。

1. テーブルを変更します（history_json と 3600 を必要な値に置き換えてください）:

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

2. 変更をすぐに適用します:

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

3. データ保存期間が変更されたことを確認します:

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. Administration > Housekeeping でデータ保存期間を更新するため、Zabbixサーバーを再起動します:

systemctl restart zabbix-server

ClickHouseクラスターの設定

このセクションでは、レプリケーションとシャーディングを備えた ClickHouse クラスターの設定手順を説明します。

以下の手順では、Docker と ClickHouse ドキュメントにある ClickHouse cluster_2S_2R（ClickHouse Keeper を使用して ClickHouse 26.4.4.38 を実行）を使用します。

開始する前に、Zabbix 用の ClickHouse クラスターの前面にロードバランサーを配置することを推奨します。
Zabbix サーバーおよび Webインターフェースの設定は単一の ClickHouse URL のみをサポートするため、1つのノードにしか接続できません。
そのノードが停止した場合でも、ロードバランサーが同じ URL を通じて、正常な別のノードへ Zabbix を振り分けます。

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

2. 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. Zabbix ディレクトリにある history_all.sh スクリプトを使用して、データベーススキーマをインポートします:

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

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

4. 各テーブル種別に対してシャーディングを設定します。
テーブル名を変更し、元の名前を持つ Distributed テーブルを作成して、変更後のテーブルを参照させます。
この Distributed テーブルが、Zabbix が実際に読み書きする対象です。テーブルはデータを自動的に各シャードへ分散します。
たとえば、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)"

5. Zabbix サーバーを設定します。

6. Zabbix Webインターフェースを設定します。

7. Zabbix データが各シャードに分散されていることを確認します。
zabbix.history_local の行数は、Zabbix サーバーが継続的に新しいデータを挿入するため、繰り返し確認すると変化する場合があります。
各ノードで次のコマンドを実行します:

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. レプリケーションが同期していることを確認します（active_replicas は 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

トラブルシューティング

以下の手順は、ClickHouse のセットアップで問題をトラブルシュートするのに役立つ場合があります。

1. ClickHouse または Zabbix サーバーのログでエラーを確認します。

2. 遅いクエリを特定するには、Zabbix サーバーの設定パラメーター HistoryProvider で log_slow_queries オプションを使用します。

3. ClickHouse が Zabbix サーバーおよび Zabbix Webインターフェースからのアクセスを許可していることを確認します。

4. ClickHouse にクエリを実行して、Zabbix によって収集されたデータが保存されているか確認します。例:

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