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
を作成します。
役立つためには、トレース情報を Jaeger や Prometheus などの 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 を実行します。
エラーが発生した場合、エラーが発生したログデータの一部は静かに失われます。データが届かない場合は、サーバーログでエラーメッセージを確認してください。