メインコンテンツまでスキップ
メインコンテンツまでスキップ

Tracing ClickHouse with OpenTelemetry

OpenTelemetry は、分散アプリケーションからトレースとメトリクスを収集するためのオープン標準です。ClickHouse は OpenTelemetry の一部をサポートしています。

ClickHouse にトレースコンテキストを供給する

ClickHouse は、W3C リコメンデーション に記載されているトレースコンテキスト HTTP ヘッダーを受け入れます。また、ClickHouse サーバー間やクライアントとサーバー間の通信に使用されるネイティブプロトコルを介してトレースコンテキストを受け入れます。手動テストの場合、Trace Context リコメンデーションに準拠したトレースコンテキストヘッダーは、clickhouse-client--opentelemetry-traceparent および --opentelemetry-tracestate フラグを使用して供給できます。

親トレースコンテキストが供給されない場合や、提供されたトレースコンテキストが上記の W3C 標準に準拠していない場合、ClickHouse は新しいトレースを開始することができます。その確率は opentelemetry_start_trace_probability 設定で制御されます。

トレースコンテキストの伝播

トレースコンテキストは、以下のケースで下流サービスに伝播されます:

  • Distributed テーブルエンジンを使用する場合の、リモート ClickHouse サーバーへのクエリ。

  • url テーブル関数。トレースコンテキスト情報は HTTP ヘッダーで送信されます。

ClickHouse 自体のトレース

ClickHouse は、各クエリおよびクエリ実行のいくつかのステージ(クエリ計画または分散クエリなど)について trace spans を作成します。

役立つためには、トレース情報を JaegerPrometheus などの OpenTelemetry をサポートする監視システムにエクスポートする必要があります。ClickHouse は特定の監視システムへの依存を避け、トレースデータをシステムテーブルを通じてのみ提供します。標準で要求される OpenTelemetry トレーススパン情報は、system.opentelemetry_span_log テーブルに保存されます。

テーブルはサーバー構成で有効にする必要があります。デフォルトの設定ファイル config.xml の中にある opentelemetry_span_log 要素を参照してください。デフォルトでは有効になっています。

タグまたは属性は、キーと値を含む 2 つの平行配列として保存されます。ARRAY JOIN を使用してこれらに対処してください。

log-query-settings

log_query_settings 設定を使用すると、クエリ実行中のクエリ設定の変更をログに記録できます。有効にすると、クエリ設定に加えられた変更は OpenTelemetry スパンログに記録されます。この機能は、クエリパフォーマンスに影響を与える可能性のある設定変更を追跡するために、特に本番環境で役立ちます。

監視システムとの統合

現在、ClickHouse から監視システムにトレースデータをエクスポートするための準備が整ったツールはありません。

テスト用に、system.opentelemetry_span_log テーブルに対して URL エンジンを使用するマテリアライズドビューを設定することで、トレースコレクタの HTTP エンドポイントにログデータをプッシュすることができます。例えば、http://localhost:9411 で稼働している Zipkin インスタンスに最小のスパンデータを Zipkin v2 JSON 形式でプッシュするには、以下の SQL を実行します。

エラーが発生した場合、エラーが発生したログデータの一部は静かに失われます。データが届かない場合は、サーバーログでエラーメッセージを確認してください。