設定を変更する最も簡単な方法は、プラグイン設定ページの Grafana UI を使用することですが、データソースは YAML ファイルを使ってプロビジョニングすることもできます。
このページでは、ClickHouse プラグインで設定可能なオプションの一覧と、YAML でデータソースをプロビジョニングする方向けの設定スニペットを紹介します。
すべてのオプションを手早く確認したい場合は、設定オプションの完全な一覧をこちらで確認できます。
設定画面の例：
共通設定の YAML 設定例：
設定をUIから保存すると、version プロパティが追加される点に注意してください。これは、その設定がどのバージョンのプラグインで保存されたかを示します。
HTTP protocol で接続を選択すると、追加の設定項目が表示されます。
HTTP サーバーが別の URL パスで公開されている場合は、ここで設定できます。
サーバーに送信するリクエストに、カスタムヘッダーを追加できます。
ヘッダーには、平文のものとセキュアなものがあります。
ヘッダー名はすべて平文で保存されますが、セキュアなヘッダーの値はセキュア設定に保存されます (password フィールドと同様です) 。
HTTP 経由でのセキュアな値セキュアなヘッダーの値は設定内で安全に保存されますが、セキュア接続が無効になっている場合、その値自体は HTTP 経由で送信されます。
otel_logs に設定してください。
これにより、デフォルトのカラムは自動的に上書きされ、選択した OTel スキーマのバージョンが使用されます。
ログで OpenTelemetry は必須ではありませんが、logs/trace で単一のデータセットを使用すると、データリンクによって、よりスムーズなオブザーバビリティのワークフローを実現できます。
ログ設定画面の例:
ログ設定 YAML の例:
トレースのクエリビルダーを高速化するには、トレースクエリ用のデフォルトのデータベース/テーブルとカラムを設定できます。これにより、実行可能なトレース検索クエリがクエリビルダーに事前に読み込まれ、Explore ページでオブザーバビリティデータをよりすばやく参照できるようになります。
OpenTelemetry を使用している場合は、「Use OTel」スイッチを有効にし、デフォルトのトレーステーブルを otel_traces に設定してください。
これにより、選択した OTel スキーマバージョンを使用するよう、デフォルトのカラムが自動的に上書きされます。
OpenTelemetry は必須ではありませんが、トレースにそのスキーマを使用する場合、この機能は最も効果的に動作します。
トレース設定画面の例:
トレース設定 YAML の例:
カラムに別名を付けると、異なる名前や型でデータをクエリできるようになり、便利です。
別名を使えば、ネストされたスキーマをフラット化して、Grafana で簡単に選択できるようにできます。
次のような場合は、別名付けが役立つ可能性があります。
- スキーマと、そのネストされたプロパティや型の大半を把握している
- データを Map 型に格納している
- JSON を文字列として保存している
- 選択するカラムを変換するために、関数をよく適用する
ClickHouse にはカラムのエイリアス機能が組み込まれており、Grafana でもそのまま利用できます。
ALIAS カラムはテーブルに直接定義できます。
上記の例では、ナノ秒のタイムスタンプを Date 型に変換する TimestampDate という別名を作成します。
このデータは最初のカラムのようにディスクに保存されず、クエリ実行時に計算されます。
テーブルで定義された別名は SELECT * では返されませんが、これはサーバー設定で変更できます。
詳細については、ALIAS カラム型のドキュメントを参照してください。
デフォルトでは、Grafana は DESC table の応答に基づいてカラム候補を提示します。
場合によっては、Grafana に表示されるカラムを完全に上書きしたいこともあります。
これにより、カラム選択時に Grafana 上でスキーマを見えにくくでき、テーブルの複雑さによってはユーザー体験の向上につながります。
テーブル定義内の別名を使う場合と比べた利点は、テーブルを変更しなくても簡単に更新できることです。スキーマによっては、これが数千件のエントリに及ぶことがあり、基になるテーブル定義が煩雑になる場合があります。また、ユーザーに無視してほしいカラムを非表示にすることもできます。
Grafana では、別名テーブルに次のカラム構造が必要です。
ALIAS カラムの動作は、別名テーブル を使って次のように再現できます。
次に、このテーブルを Grafana で使えるように設定できます。なお、名前は任意で、別のデータベースで定義することも可能です。
これで Grafana では、DESC example_table の結果ではなく、別名テーブル の結果が表示されます。
どちらのエイリアス方式も、複雑な型変換や JSON フィールドの抽出に利用できます。
以下は、このプラグインで利用できるYAML設定オプションの一覧です。
一部のフィールドには値の例があり、その他はフィールドの型のみが示されています。
YAMLを使用したデータソースのプロビジョニングの詳細については、Grafanaドキュメントを参照してください。
