可視化の作成
GROUP BY クエリに対応しており、選択した次元に対して集計するメトリクスを定義します。
たとえば、サービス名ごとにグループ化したエラーの件数 (count()) をチャートとして表示できます。
以下の例では、sql.clickhouse.com で利用できるリモートデータセットを使用します。これはガイド「Remote Demo Dataset」で説明されています。また、play-clickstack.clickhouse.com にアクセスして、これらの例を再現することもできます。
2
可視化を作成する
以下の例では、サービス名ごとの平均リクエスト時間を時系列でチャートとして表示します。これには、メトリクス、カラム (SQL 式を指定することも可能)、および集計フィールドを指定する必要があります。上部メニューから
Line/Bar の可視化タイプを選択し、続いて Traces データセット (play-clickstack.clickhouse.com を使用している場合は Demo Traces) を選択します。次の値を入力してください。- メトリクス:
Average - カラム:
Duration/1000 - Where:
<empty> - Group By:
ServiceName - 別名:
Average Time
WHERE 句または Lucene 構文のいずれかを使ってフィルタでき、イベントを可視化する時間範囲も設定できます。複数の系列にも対応しています。たとえば、フィルタ ServiceName:\"frontend\" を追加して、サービス frontend でフィルタします。さらに、Add Series をクリックして、別名 Count を持つ時系列のイベント件数の 2 つ目の系列を追加します。既存の系列に似た系列を作成するには、最初から作成する代わりに複製できます。系列行のコピーアイコン (Duplicate series) をクリックすると、そのすぐ下にコピーが挿入されます。コピーには、メトリクス、カラム、フィルタなど、元の系列の設定が保持されます。その後、異なるフィールド (たとえば集計) だけを変更し、コピーに固有の別名を付けます。複製は、複数の系列がサポートされている場所であればどこでも利用できます。Number、Pie、Heatmap など、1 つの系列しか許可しない可視化タイプでは表示されません。可視化は、メトリクス、トレース、ログなど、任意のデータソースから作成できます。ClickStack はこれらすべてをワイドイベントとして扱います。任意の numeric カラム を時系列でチャート化でき、string、date、または numeric のカラムをグループ化に使用できます。この統一されたアプローチにより、一貫性があり柔軟なモデルを使って、テレメトリーの種類をまたいだダッシュボードを構築できます。
ダッシュボードの作成
2
可視化を作成する – サービスごとの平均リクエスト時間
Add New Tileを選択して、可視化作成パネルを開きます。上部メニューからLine/Barの可視化タイプを選択し、続いてTraces (play-clickstack.clickhouse.comを使用している場合はDemo Traces) データセットを選択します。次の値を入力して、サービス名ごとの平均リクエスト所要時間を時系列で表示するチャートを作成します。- Chart Name:
Average duration by service - Metric:
Average - Column:
Duration/1000 - Where:
<empty> - Group By:
ServiceName - Alias:
Average Time
Saveをクリックする前に、playボタンをクリックします。可視化のサイズを変更し、ダッシュボードの全幅に広がるようにします。3
可視化を作成する – サービス別のイベント数の推移
Add New Tileを選択して、可視化作成パネルを開きます。上部メニューからLine/Barの可視化タイプを選択し、続いてLogs (play-clickstack.clickhouse.com を使用している場合はDemo Logs) データセットを選択します。次の値を設定して、サービス名ごとのイベント数の推移を示すチャートを作成します。- Chart Name:
Event count by service - Metric:
Count of Events - Where:
<empty> - Group By:
ServiceName - Alias:
Count of events
Saveをクリックする前に、playボタンをクリックします。可視化のサイズを調整して、ダッシュボードの全幅に広げます。4
スパン継続時間のヒートマップタイルを追加する
ヒートマップタイルは、各 (time, value) バケットに入るイベント数を色付きのグリッドで表示します。平均値や単一のパーセンタイルだけでなく、時間に伴う分布の形を見たい場合に、ヒートマップは有効です。レイテンシのヒートマップを使うと、二峰性の継続時間パターン、低速側の裾に現れるクラスター、あるいは折れ線グラフでは平均化されて見えなくなる急激な広がりを把握できます。ヒートマップタイルを追加するには:
Add New Tileを選択します。- 上部メニューから可視化タイプ
Heatmapを選択します。data source のドロップダウンには、source type がTracesのソースだけが表示されます。ヒートマップには traces ソースでのみ提供される span duration カラムが必要なため、logs、metrics、session ソースは除外されます。 - traces ソースを名前で 1 つ選択します。名前自体は任意で、重要なのは type だけです。
- Value: ソースの
Duration Expression。現在の表示単位に合わせてスケーリングされます (たとえば、各イベントのスパン継続時間をナノ秒からミリ秒に変換するには(Duration)/1e6) - Count:
count()
- chart 名を設定し、
Whereを使って、パフォーマンスを観測したい特定のサービスまたは一連のオペレーションにヒートマップの対象を絞ります。 - 関心のある期間に合わせて時間範囲を調整します。より広い範囲を指定すると、短いウィンドウでは見えにくい分布の変化や二峰性のレイテンシパターンを把握できます。
Run をクリックして chart をプレビューし、次に Save をクリックします。保存したタイルは、ダッシュボード上でヒートマップとして表示されます。任意のセルにホバーすると、バケットの範囲とイベント数を確認できます。イベントデルタにドリルダウンする
表示されたヒートマップタイル内の任意のセルをクリックすると、View in Event Deltas アクションが開きます。これを選択すると、タイルの data source、Where clause、時間範囲が引き継がれた状態で イベントデルタ ビューが開きます。そこから、同じ分布を対話的に調べたり、attribute ごとに切り分けて低速の spans が高速のものと何が違うのかを確認したり、手作業でクエリを組み直すことなく、任意のセルの背後にある個々の spans を調査したりできます。5
ダッシュボードのフィルター
Lucene または SQL のフィルターは、時間範囲とあわせてダッシュボード レベルで適用でき、すべての可視化に自動的に反映されます。例として、Lucene フィルター
ServiceName:"frontend" をダッシュボードに適用し、時間範囲を過去 3 時間に変更します。可視化に frontend サービスのデータだけが反映されるようになることを確認してください。ダッシュボードは自動保存されます。ダッシュボード名を設定するには、タイトルを選択して編集し、Save Name をクリックします。ダッシュボード - 可視化の編集
タイルの表示設定
数値タイルの色
セマンティックトークン (ステータス向け) :
数値がステータスを表す場合は、セマンティックトークンを使用します (例: エラー数には
chart-error、正常率には chart-success) 。ステータスを示さずに関連する KPI タイルを視覚的に区別したい場合は、カテゴリトークンを使用します。
古い設定では、従来の数値トークン (chart-1 ～ chart-10) が保存されている場合があります。ClickStack はダッシュボードの読み込み時に、これらを上記の色相名付きトークンにマッピングします。
同じパレットは、同じドロワー内で任意に設定できるカラールールにも使用されます。カラールールは表示値に対して順番に評価される条件で、最後に一致したルールが優先されます。どのルールにも一致しない場合は、静的な色が適用され、それもない場合はデフォルトのテキスト色が使用されます。
数値タイルの Background chart
Dashboards API: 数値タイルの色
POST / PUT /api/v2/dashboards) を使用してダッシュボードを作成または更新する場合は、builder の数値タイル 設定 の color にパレットトークンを設定します。生の 16 進数値は使用できません。
color には、上記のカテゴリ別およびセマンティックのリストにある任意の トークン (例: chart-blue または chart-success) を指定できます。任意の backgroundChart.color で、同じ トークン enum を使用してスパークラインの色を上書きできます。認証とベース URL については、ClickStack API リファレンスを参照してください。
ダッシュボード - 一覧と検索
ダッシュボード - タグ付け
- 整理方法: タグは左側のサイドバーに表示され、ダッシュボードと保存済み検索は割り当てられたタグごとにグループ化されます
- 複数のタグ: 1 つの項目に複数のタグを追加して、より適切に分類できます
- 自動作成: まだ存在しないタグを割り当てると、そのタグは自動的に作成されます
- 簡単な管理: 整理方法に合わせて、タグはいつでも追加または削除できます
カスタムフィルタと変数
- ブロードキャスト — 一致するタイルにフィルタ条件として選択内容を適用します。タイルを更新してフィルタを参照する必要はありません。
- 変数 — 選択内容を
$variableNameとしてタイルのクエリで利用できるようにし、各タイルで値を使用する場所と方法を決定できます。
1
Edit Filters ダイアログを開く
保存済みダッシュボードを開き、ツールバーから Edit Filters and Variables を選択します。
2
新しいフィルタを追加する
Add new filter をクリックします。Display Name を入力し、データソース を選択し、Filter expression (ドロップダウンに表示する値を生成する SQL のカラムまたは式) を入力してフィルタを設定します。Save filter をクリックします。たとえば、トレースデータ用のサービスフィルタを追加するには、
Traces データソースで ServiceName をフィルタ式として使用します。“Dropdown values filter” は任意で、ドロップダウンに表示する値を絞り込めます。同じダイアログでは、以下で説明するフィルタ値をブロードキャストするかどうか、および変数として利用可能にするかどうかも設定できます。Filters モーダルには、そのダッシュボードに設定されているすべてのフィルタが表示されます。ここから既存のフィルタを編集または削除したり、追加したりできます。3
フィルタを使用する
Filters モーダルを閉じます。新しいドロップダウンフィルタが検索バーの下に表示されます。クリックして利用可能な値を確認し、1 つ選択すると、ダッシュボード上のすべての可視化にフィルタが適用されます。
4
(任意) フィルタ値をデフォルトとして保存する
フィルタの選択をダッシュボードのデフォルトとして保持するには、ダッシュボードメニューから Save Query & Filters as Default を選択します。以後、ダッシュボードは選択したフィルタが適用された状態で常に開きます。リセットするには、同じメニューから Remove Default Query & Filters を選択します。
カスタムのドロップダウンフィルタは保存済みダッシュボードで利用できます。この機能の実例については、Kubernetes ダッシュボードを参照してください。ここでは、ポッド、デプロイメント、ノード名、ネームスペース、クラスター向けの組み込みドロップダウンフィルタが提供されています。
ブロードキャスト
$__filters マクロを含め、ログソースを選択する必要があります。ClickStack は手書きのクエリ内で条件を適用する箇所を推論できないためです。
変数
$variableName としてタイルクエリでも使用できます。Variable name のデフォルトは、使用できない文字を削除したフィルタの表示名ですが、変更できます。名前は文字で始め、文字、数字、アンダースコアのみを使用できます。
WHERE 条件をブロードキャストしたくない場合は、変数を使用します。たとえば、値を SELECT 式、HAVING 句、結合キーで使用する場合や、フィルタ自身の式とは異なるカラムでタイルをフィルタリングする場合です。
変数の参照
何も選択されていない場合、
$name は NULL としてレンダリングされます。そのため、SQL述語が必要な箇所では、以下のマクロを使用してください。どちらのマクロも、変数が未選択の場合は 1=1 に展開されるため、クエリは有効なままです。
チャートビルダーのタイルで変数を使用する
SELECT カラム、系列ごとの式、WHERE、GROUP BY、HAVING が含まれます。エディタではダッシュボードの変数が自動補完され、現在の選択に応じて各参照がどのように展開されるかが表示されます。
SQL モードでは、変数が未選択の場合でもクエリが有効なままとなるよう、$__filter および $__conditionalAll マクロを使用することを推奨します。Lucene 入力ではマクロを使用できないため、代わりに生の変数を参照してください (例: ServiceName:$service) 。
Lucene 入力では、変数参照自体を引用符で囲むかどうかによって、複数値の選択をどのように照合するかが決まります。$service で a,b を選択した場合:
選択した値を部分文字列ではなく
Field と完全一致させる場合は、変数参照を引用符で囲んでください — Field:"$var"。
SQL タイルで変数を使用する
ダッシュボード変数を参照するタイルのアラートは、ダッシュボードで選択した値ではなく、すべての変数が空の状態で評価されます。
検索へのドリルダウン
- すべてのイベントを表示 — 選択した時間範囲内のすべてのイベントを表示するSearchページに移動します。
- グループで絞り込む — 特定の系列で絞り込んだSearchページに移動します。
プリセット
ClickHouse ダッシュボード
必要なシステムテーブルへのアクセス権このダッシュボードでは、主要なメトリクスを表示するために ClickHouse の システムテーブル をクエリします。次の権限が必要です。
GRANT SHOW COLUMNS, SELECT(CurrentMetric_MemoryTracking, CurrentMetric_S3Requests, ProfileEvent_OSCPUVirtualTimeMicroseconds, ProfileEvent_OSReadChars, ProfileEvent_OSWriteChars, ProfileEvent_S3GetObject, ProfileEvent_S3ListObjects, ProfileEvent_S3PutObject, ProfileEvent_S3UploadPart, event_time) ON system.metric_logGRANT SHOW COLUMNS, SELECT(active, database, partition, rows, table) ON system.partsGRANT SHOW COLUMNS, SELECT(event_date, event_time, memory_usage, normalized_query_hash, query, query_duration_ms, query_kind, read_rows, tables, type, written_bytes, written_rows) ON system.query_logGRANT SHOW COLUMNS, SELECT(event_date, event_time, hostname, metric, value) ON system.transposed_metric_log