ClickStack の可視化とダッシュボード

ClickStack ではイベントを可視化でき、ClickStack UI (HyperDX) にはグラフ化機能が標準で備わっています。これらのチャートはダッシュボードに追加して、他のユーザーと共有できます。

可視化は、トレース、メトリクス、ログ、またはユーザー定義の任意のワイドイベントスキーマから作成できます。

HyperDX の Chart Explorer インターフェイスでは、メトリクス、トレース、ログを時系列で可視化できるため、データ分析用の可視化をすばやく作成できます。このインターフェイスは、ダッシュボードの作成時にも使用されます。以下では、Chart Explorer を使って可視化を作成する手順を説明します。

各可視化は、まず データソース を選択し、続いて メトリクス を選択することから始まります。必要に応じて フィルタ式 と group by フィールドも指定できます。概念的には、HyperDX の可視化は内部的に SQL の GROUP BY クエリに対応しており、選択した次元に対して集計するメトリクスを定義します。

たとえば、サービス名ごとにグループ化したエラーの件数 (count()) をチャートとして表示できます。

以下の例では、sql.clickhouse.com で利用できるリモートデータセットを使用します。これはガイド「Remote Demo Dataset」で説明されています。また、play-clickstack.clickhouse.com にアクセスして、これらの例を再現することもできます。

Chart Explorer に移動する

左側のメニューから Chart Explorer を選択します。

可視化を作成する

以下の例では、サービス名ごとの平均リクエスト時間を時系列でチャートとして表示します。これには、メトリクス、カラム (SQL 式を指定することも可能)、および集計フィールドを指定する必要があります。

上部メニューから Line/Bar の可視化タイプを選択し、続いて Traces データセット (play-clickstack.clickhouse.com を使用している場合は Demo Traces) を選択します。次の値を入力してください。

• メトリクス: Average
• カラム: Duration/1000
• Where: <empty>
• Group By: ServiceName
• 別名: Average Time

イベントは SQL の WHERE 句または Lucene 構文のいずれかを使ってフィルタでき、イベントを可視化する時間範囲も設定できます。複数の系列にも対応しています。

たとえば、フィルタ ServiceName:\"frontend\" を追加して、サービス frontend でフィルタします。さらに、Add Series をクリックして、別名 Count を持つ時系列のイベント件数の 2 つ目の系列を追加します。

既存の系列に似た系列を作成するには、最初から作成する代わりに複製できます。系列行のコピーアイコン (Duplicate series) をクリックすると、そのすぐ下にコピーが挿入されます。コピーには、メトリクス、カラム、フィルタなど、元の系列の設定が保持されます。その後、異なるフィールド (たとえば集計) だけを変更し、コピーに固有の別名を付けます。複製は、複数の系列がサポートされている場所であればどこでも利用できます。Number、Pie、Heatmap など、1 つの系列しか許可しない可視化タイプでは表示されません。

ダッシュボードを使うと、関連する可視化をグループ化できるため、メトリクスを比較したり、パターンを並べて確認したりしながら、システム内の潜在的な根本原因を特定できます。これらのダッシュボードは、アドホックな調査に使用することも、継続的な監視用に保存して利用することもできます。

グローバルフィルターはダッシュボードレベルで適用でき、対象のダッシュボード内にあるすべての可視化に自動的に反映されます。これにより、チャート間で一貫したドリルダウンが可能になり、サービスやテレメトリーの種類をまたいだイベントの相関を取りやすくなります。

以下では、ログおよびトレースのデータソースを使用して、2 つの可視化を含むダッシュボードを作成します。これらの手順は、play-clickstack.clickhouse.com 上でも、ガイド「Remote Demo Dataset」で説明されているように sql.clickhouse.com でホストされているデータセットに接続してローカル環境でも再現できます。

Dashboards を開く

左側のメニューから Dashboards を選択します。次に New Dashboard をクリックして、一時的なダッシュボードまたは保存済みのダッシュボードを作成します。

可視化を作成する – サービスごとの平均リクエスト時間

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ボタンをクリックします。

可視化のサイズを変更し、ダッシュボードの全幅に広がるようにします。

可視化を作成する – サービス別のイベント数の推移

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ボタンをクリックします。

可視化のサイズを調整して、ダッシュボードの全幅に広げます。

スパン継続時間のヒートマップタイルを追加する

ヒートマップタイルは、各 (time, value) バケットに入るイベント数を色付きのグリッドで表示します。平均値や単一のパーセンタイルだけでなく、時間に伴う分布の形を見たい場合に、ヒートマップは有効です。レイテンシのヒートマップを使うと、二峰性の継続時間パターン、低速側の裾に現れるクラスター、あるいは折れ線グラフでは平均化されて見えなくなる急激な広がりを把握できます。

ヒートマップタイルを追加するには:

1. Add New Tile を選択します。
2. 上部メニューから可視化タイプ Heatmap を選択します。data source のドロップダウンには、source type が Traces のソースだけが表示されます。ヒートマップには traces ソースでのみ提供される span duration カラムが必要なため、logs、metrics、session ソースは除外されます。
3. traces ソースを名前で 1 つ選択します。名前自体は任意で、重要なのは type だけです。

ソースを選択すると、ヒートマップには次の値が事前入力されます:

• Value: ソースの Duration Expression。現在の表示単位に合わせてスケーリングされます (たとえば、各イベントのスパン継続時間をナノ秒からミリ秒に変換するには (Duration)/1e6)
• Count: count()

4. chart 名を設定し、Where を使って、パフォーマンスを観測したい特定のサービスまたは一連のオペレーションにヒートマップの対象を絞ります。
5. 関心のある期間に合わせて時間範囲を調整します。より広い範囲を指定すると、短いウィンドウでは見えにくい分布の変化や二峰性のレイテンシパターンを把握できます。

以下の例では、24 時間のウィンドウにおける単一サービスを示しており、そのスパン継続時間の高速パスと低速パスが 2 本の水平帯として明確に分かれています。

さらにヒートマップをカスタマイズするには、Display Settings をクリックして、Scale (Log または Linear) 、Value、Count expression を設定するドロワーを開きます。オプションの一覧は、イベントデルタのページにある ヒートマップをカスタマイズする に記載されています。同じドロワーが再利用されます。

Run をクリックして chart をプレビューし、次に Save をクリックします。

保存したタイルは、ダッシュボード上でヒートマップとして表示されます。任意のセルにホバーすると、バケットの範囲とイベント数を確認できます。

イベントデルタにドリルダウンする

表示されたヒートマップタイル内の任意のセルをクリックすると、View in Event Deltas アクションが開きます。

これを選択すると、タイルの data source、Where clause、時間範囲が引き継がれた状態で イベントデルタ ビューが開きます。そこから、同じ分布を対話的に調べたり、attribute ごとに切り分けて低速の spans が高速のものと何が違うのかを確認したり、手作業でクエリを組み直すことなく、任意のセルの背後にある個々の spans を調査したりできます。

ダッシュボードのフィルター

Lucene または SQL のフィルターは、時間範囲とあわせてダッシュボード レベルで適用でき、すべての可視化に自動的に反映されます。

例として、Lucene フィルター ServiceName:"frontend" をダッシュボードに適用し、時間範囲を過去 3 時間に変更します。可視化に frontend サービスのデータだけが反映されるようになることを確認してください。

ダッシュボードは自動保存されます。ダッシュボード名を設定するには、タイトルを選択して編集し、Save Name をクリックします。

可視化を削除、編集、または複製するには、その上にカーソルを合わせて、対応するアクションボタンを使用します。

各タイルには、値の表示方法を制御するための Display Settings ドロワーがあります。タイルエディタで Display Settings をクリックすると開けます。利用できるオプションは、可視化の種類によって異なります。

数値タイルでは、厳選されたチャートパレットから静的な色を選択できます。数値タイルを選択した状態で表示設定を開き、色コントロール (アクセシビリティ用のラベルは数値タイルの色) から色見本を選択します。選択を解除すると、デフォルトのテキスト色が使用されます。

色は生の16進数値ではなくパレットトークンとして保存されるため、ライト、ダーク、IDE の各テーマでも同じタイルが適切に表示されます。

カテゴリトークン (複数系列用の色相) :

セマンティックトークン (ステータス向け) :

数値がステータスを表す場合は、セマンティックトークンを使用します (例: エラー数には chart-error、正常率には chart-success) 。ステータスを示さずに関連する KPI タイルを視覚的に区別したい場合は、カテゴリトークンを使用します。

古い設定では、従来の数値トークン (chart-1 ～ chart-10) が保存されている場合があります。ClickStack はダッシュボードの読み込み時に、これらを上記の色相名付きトークンにマッピングします。

同じパレットは、同じドロワー内で任意に設定できるカラールールにも使用されます。カラールールは表示値に対して順番に評価される条件で、最後に一致したルールが優先されます。どのルールにも一致しない場合は、静的な色が適用され、それもない場合はデフォルトのテキスト色が使用されます。

数値タイルでは Background chart を表示できます。これは値の背後に描かれるトレンドのスパークラインで、選択した time range における推移をひと目で確認できます。SLO や error-budget タイルでは、現在の値だけでなく、その値がどう推移しているかも重要になるため、特に便利です。

数値タイルを選択した状態で Display Settings を開き、Background chart を Line または Area に設定します (無効にする場合は None) 。このスパークラインは、タイルのクエリを time-bucketed した結果から生成されるため、追加の設定は不要です。既定ではタイルの色を引き継ぎますが、特定のパレット色を使いたい場合は Background color を設定して上書きできます。

Background chart は、query-builder の 数値タイルに適用されます。Raw SQL の 数値タイルは、bucket 化できる time dimension を持たない単一の値しか返さないため、このオプションは表示されますが無効になっています。

Table タイルでは Alternate Row Background を使って行を交互に色分けできるため、列数の多いテーブルでも確認しやすくなります。これは既定ではオフです。

Table タイルを選択した状態で Display Settings を開き、Alternate Row Background をオンにします。交互の色分けは見た目だけの設定なので、query-builder と raw SQL の両方のテーブルタイルで機能します。

テーブルタイルでは、スクロールしてもヘッダー行とデータの間の区切り線が維持されるため、カラム見出しを見分けやすくなります。

外部 API (POST / PUT /api/v2/dashboards) を使用してダッシュボードを作成または更新する場合は、builder の数値タイル 設定 の color にパレットトークンを設定します。生の 16 進数値は使用できません。

{
  "name": "Error rate KPIs",
  "tiles": [
    {
      "id": "65f5e4a3b9e77c001a222222",
      "name": "Errors",
      "x": 0,
      "y": 0,
      "w": 6,
      "h": 4,
      "config": {
        "displayType": "number",
        "sourceId": "<SOURCE_ID>",
        "select": [
          {
            "aggFn": "count",
            "where": "SeverityText:error",
            "whereLanguage": "lucene",
            "alias": "Errors"
          }
        ],
        "color": "chart-error",
        "backgroundChart": {
          "type": "area"
        }
      }
    }
  ]
}

color には、上記のカテゴリ別およびセマンティックのリストにある任意の トークン (例: chart-blue または chart-success) を指定できます。任意の backgroundChart.color で、同じ トークン enum を使用してスパークラインの色を上書きできます。認証とベース URL については、ClickStack API リファレンスを参照してください。

ダッシュボードは dashboards ページから利用できます。タグごとに整理されており、組み込みの検索機能と絞り込み機能を使って特定のダッシュボードをすばやく見つけられます。

ダッシュボードはお気に入りに追加でき、サイドバーや一覧ページ上部から簡単にアクセスできます。お気に入りはユーザーごとに個別に管理されます。

ダッシュボードや保存済み検索にタグを追加すると、整理しやすくなります。 タグを使うことで、必要に応じて柔軟に分類したり絞り込んだりできます。

• 整理方法: タグは左側のサイドバーに表示され、ダッシュボードと保存済み検索は割り当てられたタグごとにグループ化されます
• 複数のタグ: 1 つの項目に複数のタグを追加して、より適切に分類できます
• 自動作成: まだ存在しないタグを割り当てると、そのタグは自動的に作成されます
• 簡単な管理: 整理方法に合わせて、タグはいつでも追加または削除できます

これにより、関連する項目を簡単に見つけられ、項目が増えても整理されたワークスペースを維持できます。

また、複数のタグを選択して、異なるカテゴリにまたがる項目を絞り込んで表示することもできます。

すべてのダッシュボードで利用できるフリーテキストフィルタに加えて、保存済みダッシュボードでは、ClickHouse にクエリしたデータをもとに値が設定されるカスタムのドロップダウンフィルタも利用できます。これにより、再利用可能なポイント＆クリック式のフィルタ操作が可能になり、ダッシュボードの閲覧者は式を手動で入力しなくても絞り込みを行えます。

各フィルタでは、閲覧者が1つ以上の値を選択でき、その値に対して次のいずれか、または両方を実行します。

• ブロードキャスト — 一致するタイルにフィルタ条件として選択内容を適用します。タイルを更新してフィルタを参照する必要はありません。
• 変数 — 選択内容を $variableName としてタイルのクエリで利用できるようにし、各タイルで値を使用する場所と方法を決定できます。

フィルタでは、この2つのうち少なくとも1つを実行する必要があります。フィルタの作成時には、ブロードキャストがデフォルトで有効になります。

以下の手順では、"ダッシュボードの作成"セクションで作成したダッシュボードにフィルタを追加する方法を示します。

Edit Filters ダイアログを開く

保存済みダッシュボードを開き、ツールバーから Edit Filters and Variables を選択します。

新しいフィルタを追加する

Add new filter をクリックします。Display Name を入力し、データソース を選択し、Filter expression (ドロップダウンに表示する値を生成する SQL のカラムまたは式) を入力してフィルタを設定します。Save filter をクリックします。

たとえば、トレースデータ用のサービスフィルタを追加するには、Traces データソースで ServiceName をフィルタ式として使用します。"Dropdown values filter" は任意で、ドロップダウンに表示する値を絞り込めます。

同じダイアログでは、以下で説明するフィルタ値をブロードキャストするかどうか、および変数として利用可能にするかどうかも設定できます。

Filters モーダルには、そのダッシュボードに設定されているすべてのフィルタが表示されます。ここから既存のフィルタを編集または削除したり、追加したりできます。

フィルタを使用する

Filters モーダルを閉じます。新しいドロップダウンフィルタが検索バーの下に表示されます。クリックして利用可能な値を確認し、1 つ選択すると、ダッシュボード上のすべての可視化にフィルタが適用されます。

(任意) フィルタ値をデフォルトとして保存する

フィルタの選択をダッシュボードのデフォルトとして保持するには、ダッシュボードメニューから Save Query & Filters as Default を選択します。以後、ダッシュボードは選択したフィルタが適用された状態で常に開きます。リセットするには、同じメニューから Remove Default Query & Filters を選択します。

フィルタ条件をブロードキャストを有効にすると、選択した値が、フィルタを明示的に参照していないダッシュボードのタイルにもフィルタ条件として適用されます。デフォルトでは、この条件はすべてのタイルに適用されます。ログソースに適用を使用すると、指定したログソースを使用するタイルにのみ適用できます。これは、フィルタ式がダッシュボード内の一部のデータに対してのみ意味を持つ場合に便利です。

チャートビルダーのタイルには、ブロードキャストフィルタが自動的に適用されます。Raw SQL タイルでは、$__filters マクロを含め、ログソースを選択する必要があります。ClickStack は手書きのクエリ内で条件を適用する箇所を推論できないためです。

Available as variable を有効にすると、フィルタの選択内容を $variableName としてタイルクエリでも使用できます。Variable name のデフォルトは、使用できない文字を削除したフィルタの表示名ですが、変更できます。名前は文字で始め、文字、数字、アンダースコアのみを使用できます。

WHERE 条件をブロードキャストしたくない場合は、変数を使用します。たとえば、値を SELECT 式、HAVING 句、結合キーで使用する場合や、フィルタ自身の式とは異なるカラムでタイルをフィルタリングする場合です。

変数は、ドロップダウンで現在選択されている値に展開されます。参照形式によってレンダリング方法が決まります。

何も選択されていない場合、$name は NULL としてレンダリングされます。そのため、SQL述語が必要な箇所では、以下のマクロを使用してください。どちらのマクロも、変数が未選択の場合は 1=1 に展開されるため、クエリは有効なままです。

チャートビルダーのすべての SQL 式入力で変数参照を使用できます。対象には、SELECT カラム、系列ごとの式、WHERE、GROUP BY、HAVING が含まれます。エディタではダッシュボードの変数が自動補完され、現在の選択に応じて各参照がどのように展開されるかが表示されます。

SQL モードでは、変数が未選択の場合でもクエリが有効なままとなるよう、$__filter および $__conditionalAll マクロを使用することを推奨します。Lucene 入力ではマクロを使用できないため、代わりに生の変数を参照してください (例: ServiceName:$service) 。

Lucene 入力では、変数参照自体を引用符で囲むかどうかによって、複数値の選択をどのように照合するかが決まります。$service で a,b を選択した場合:

選択した値を部分文字列ではなく Field と完全一致させる場合は、変数参照を引用符で囲んでください — Field:"$var"。

Raw SQL タイルでは、クエリ内のどの箇所でも同じように変数を参照できます。

SELECT
  $__timeInterval(TimestampTime) AS ts,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filter(ServiceName, $service)
  AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY ts
ORDER BY ts ASC

SQL タイルで使用できるマクロの一覧については、SQL ベースの可視化を参照してください。

ダッシュボードのタイルは、Searchページへのドリルダウンに対応しています。可視化内のデータポイントをクリックすると、次のオプションを含むコンテキストメニューが表示されます。

• すべてのイベントを表示 — 選択した時間範囲内のすべてのイベントを表示するSearchページに移動します。
• グループで絞り込む — 特定の系列で絞り込んだSearchページに移動します。

これは、ダッシュボードで見つけた特定のスパイクや異常を調査する際に便利です。集計ビューから、元になっている個々のイベントへすばやく移れます。

HyperDX には、すぐに使えるダッシュボードがあらかじめ用意されています。

このダッシュボードでは、ClickHouse の監視に役立つ可視化を提供します。このダッシュボードを開くには、左側のメニューから選択します。

このダッシュボードでは、タブを使って Selects、Inserts、ClickHouse Infrastructure の監視を分けています。

サービス ダッシュボードには、トレースデータに基づいて現在アクティブなサービスが表示されます。これを利用するには、トレースを収集し、有効な Traces データソースを設定しておく必要があります。

サービス名はトレースデータから自動検出され、あらかじめ用意された一連の可視化が、HTTP Services、Database、Errors の 3 つのタブに分けて表示されます。

可視化は Lucene または SQL 構文を使ってフィルタリングでき、分析対象を絞り込めるよう時間範囲も調整できます。

このダッシュボードでは、OpenTelemetry 経由で収集された Kubernetes イベントを確認できます。高度な絞り込みオプションが用意されており、Kubernetes のポッド、デプロイメント、ノード名、ネームスペース、クラスターで絞り込めるほか、自由入力のテキスト検索も行えます。

Kubernetes データは、ナビゲーションしやすいように Pods、Nodes、Namespaces の 3 つのタブに整理されています。