cx-dashboards

Coralogix ダッシュボードの作成

対象サービス向けの Coralogix ダッシュボードを作成し、cx CLI を使ってデプロイします。ワークフローは、サービスのテレメトリを調査し、ユーザーと意図をすり合わせ、計画を作成し、JSON を出力して、cx ですべてのクエリを実行時に検証したうえで、選択したフォルダーにダッシュボードを作成する流れです。

サービスのコード、README、設定、または結果が返されたライブクエリで根拠を示せるメトリクス名、ログフィールド、スパン属性だけを使用してください。推測で作成してはいけません。

---

参考ファイル

ドメイン固有のガイダンスについては、次のファイルを読み込んでください。

タスク	参考資料
DataPrime クエリ構文	references/dataprime-reference.md
PromQL クエリ構文、カウンターとゲージ、ヒストグラム	references/promql-guidelines.md
ログフィールドの調査、クエリパターン、wildfind のポリシー	references/logs-querying.md
スパンフィールドの調査、レイテンシ分析、トレースクエリ	references/spans-querying.md
ダッシュボード固有のクエリに関する注意点（${__range}、promqlQueryType）	references/query-syntax.md
ウィジェットの JSON テンプレート	references/widget-templates.md

適切なシグナル（メトリクス／ログ／トレース）を選ぶには、cx-telemetry-querying を使用してください。

---

ダッシュボードの管理

ダッシュボードの作成に加え、既存のダッシュボードの管理には次のコマンドを使用します。

コマンド	目的
cx dashboards catalog -o json	カタログ内のすべてのダッシュボードを一覧表示する
cx dashboards get <id> -o json	ダッシュボード定義を取得する（テンプレートとして便利）
cx dashboards folders list -o json	ダッシュボードフォルダーを一覧表示する
cx dashboards folders create --name "Name"	ダッシュボードフォルダーを作成する
cx dashboards folders create --name "Sub" --parent-id <id>	入れ子のフォルダーを作成する
cx dashboards replace --from-file dashboard.json	更新した JSON で既存のダッシュボードを置き換える
cx dashboards check --from-file dashboard.json	保存せずにダッシュボード定義を検証する（サーバー側の厳密なチェック。エラー時はゼロ以外で終了する）
cx dashboards check <dashboard-id>	ID で保存済みのダッシュボードを検証する

既存のダッシュボードを更新するには：

cx dashboards get <dashboard-id> -o json > dashboard.json
# Edit dashboard.json (change name, modify widgets, etc.)
cx dashboards replace --from-file dashboard.json

ダッシュボードを新しいコピーとして複製するには：

cx dashboards get <dashboard-id> -o json > dashboard.json
# Remove the "id" field, then create as new:
cx dashboards create --from-file dashboard.json

---

ワークフロー

次のチェックリストで進捗を管理してください。

Dashboard Progress:
- [ ] Phase 1: Discover telemetry & business meaning
- [ ] Phase 2: Gather dashboard specifications from user
- [ ] Phase 3: Draft internal dashboard plan (sections/rows/widgets)
- [ ] Phase 4: Generate the Coralogix JSON
- [ ] Phase 5: Live-verify every query through the cx CLI
- [ ] Phase 6: Self-verify structure against the checklist
- [ ] Phase 7: Server-side validation via `cx dashboards check`
- [ ] Phase 8: Deploy via `cx dashboards create`
- [ ] Phase 9: Share the dashboard link with the user

順番に進めてください。ユーザーがフェーズ 3 の計画を承認する前にフェーズ 4 に進んではいけません。また、フェーズ 5～7 がすべて成功する前にフェーズ 8 を実行してはいけません。フェーズ 9 は必須です。ユーザーがクリックできるリンクを受け取るまで、ワークフローは完了していません。

フェーズ 1：テレメトリとビジネス上の意味を把握する

対象サービスについて、以下を確認します。

1. ビジネス上の目的 - README.md と最上位のエントリポイント（main.*、index.*、cmd/main.go など）を読みます。サービスの機能、主な処理段階、問題が起こり得る箇所を、2～3 文でまとめます。
2. メトリクス - 候補キーワード（サービス名、サブシステム、request、error、latency、dlq などの動詞や語句）ごとに、cx metrics search --name '*<keyword>*' を実行します。有望なメトリクスが見つかったら、cx metrics get-labels <metric> でラベルを一覧表示します。cx metrics search が返した名前だけを使います。これにより、存在しないメトリクスがフェーズ 5 に含まれるのを防げます。サービスの計装（prometheus_client、promauto.NewCounter/Histogram/Gauge、OTel メーター、prom-client、Micrometer、metrics.py）と照合して、意味やヒストグラムのバケット（_sum、_count、_bucket）を確認します。
3. ログ - フィールドの存在を前提とする前に、cx search-fields "<description>" --dataset logs でカスタムの $d.* フィールドを調べます。cx logs "filter \$l.applicationname == '<app>'" --limit 5 -o json でメッセージテンプレートと重大度のサンプルを取得します。標準フィールド（$m.severity、$m.timestamp、$l.applicationname、$l.subsystemname）は事前に調べる必要はありません。
4. スパン／トレース - cx search-fields "<description>" --dataset spans でスパン属性を調べます。cx spans "filter \$l.serviceName == '<svc>'" --limit 5 -o json でサンプルを取得します。エラーの規約（$d.tags.error、$d.http.status_code）はサービスによって異なるため、フィルターを設定する前にサンプルを確認します。
5. メッセージバスと DLQ - Kafka、RabbitMQ、SQS、Pub/Sub のクライアント、および dlq／DLQ の記述を検索します。DLQ パネル用にトピック名／キュー名を記録します。
6. サービス設定 - meta.yaml、Helm の values.yaml、Deployment、Dockerfile、chart.yaml を確認します。以下を抽出します。
   • Coralogix に表示される applicationname／subsystemname ラベルの値。
   • メトリクスまたはログのラベルとして使われるテナント／アカウント／チームの識別子。
   • デプロイ環境（prod、staging、dev など）。

質問に対するシグナルが曖昧な場合（例：「先週の収益はいくらか」）、まず cx-telemetry-querying に依頼します。

次のフェーズに進む前に、内部向けの短い概要を作成します。重要なテレメトリが不足している場合（例：メトリクスがない）、そのことをユーザーに伝え、ログのみ、またはトレースのみのダッシュボードを希望するか確認します。

---

フェーズ 2：ダッシュボードの仕様を収集する

ユーザーには、的を絞った質問を 6 件以内で尋ねます。AskQuestion を優先します。

1. 対象者と用途 - オンコール時のトリアージ、製品／ビジネスの追跡、キャパシティプランニング、カスタマーサクセスのどれですか？
2. デフォルトの時間範囲 - 通常どの期間を表示しますか（例：24h、7d）。ユーザーがズームできるよう、クエリでは引き続き ${__range} を使います。
3. スライスのディメンション - 最上位のフィルター（tenant_id、account_id、subsystem_name、region、env など）。
4. 環境の対象範囲 - 含める／除外する環境（一般的なデフォルトでは dev、staging、test を除外します）。
5. SLO に近いシグナル - 成功率、レイテンシ、スループットのどの目標を強調しますか？
6. 優先事項 - 最初に何を表示しますか（行の順序と、どのセクションを collapsed: true にするかが決まります）。

妥当に推測できる回答を待って作業を止めないでください。推測した内容を示し、そのまま進めます。

---

フェーズ 3：内部プランを作成する

JSON の生成前に、ユーザーが承認できる Markdown 形式のプランを作成します。

## Dashboard: <Service> - <Purpose>

### Section 1: <Overview> (collapsed: false)
- Row 1: [widget type] <title> - <what it shows> - source: metrics|logs|spans
- Row 2: ...

### Section 2: <Deep dive> (collapsed: false)
...

### Section N: <Logs & errors> (collapsed: true)
...

### Top-level filters
- <label> (<source>)

### Assumptions / gaps
- ...

セクションの設計：

• 最初のセクション：概要をひと目で把握できるヘルス情報（ゲージ＋主要なレート）。常に展開します。
• 関連する時系列データ（レート＋レイテンシ）は同じ行に配置します。
• 最後のセクション（生ログ、まれな内訳）：collapsed: true を設定します。
• セクションは 3～5 個、ウィジェットは合計 6～20 個を目安にします。

ウィジェットタイプの選択：

シグナル	ウィジェットタイプ
メトリクスクエリから得られる単一の見出し数値（カウント、成功率、合計など）	gauge（Coralogix では「stat」と呼ばれます）
メトリクスクエリから得られる 8 カテゴリ以下の内訳	pieChart
メトリクスクエリから得られる時間経過に伴う変化（レート、レイテンシ、バケットあたりのカウント）	lineChart
任意のクエリによる上位 N 件のテーブルや一覧（PromQL の topk を含む）	table ビジュアライゼーションを使った dynamic（従来の dataTable は使用しないでください）
ログ、スパン、または DataPrime に対するクエリ	形状テーブルに応じたビジュアライゼーションを使った dynamic

ユーザーからの依頼がない限り、他のウィジェットタイプは使用しないでください。

ログ、スパン、DataPrime のウィジェットは dynamic で、ビジュアライゼーションを設定します。 どのクエリでも、従来の dataTable ウィジェットは出力しないでください。PromQL の上位 N 件テーブルも、metrics クエリと table ビジュアライゼーションを使った dynamic ウィジェットです。definition.dynamic を使い、クエリの形状に合ったグラフを visualization に設定します。table が適切なのは、ユーザーが読みたい生の行に限ります。クエリのすべての列にエイリアスを付け、ビジュアライゼーションではそのエイリアスを指定します。形状とビジュアライゼーションの対応表およびテンプレートについては、references/widget-templates.md → Widget: dynamic を参照してください。

JSON を出力する前に、ユーザーがプランを承認するか、調整するのを待ちます。

---

フェーズ 4：Coralogix JSON を生成する

references/widget-templates.md に従って、単一の JSON ドキュメントを作成します。主なルールは次のとおりです。

1. トップレベルの構造：

   {
     "id": "<21-char-nanoid>",
     "name": "<Dashboard Name>",
     "layout": { "sections": [ ... ] },
     "variables": [],
     "variablesV2": [],
     "filters": [ ... ],
     "relativeTimeFrame": "<seconds>s",
     "annotations": [],
     "off": {},
     "actions": []
   }
   

2. ID - section、row、widget、クエリの各 id に、新しい UUID を割り当てます。
3. 行の高さ - 変更する理由がない限り、"appearance": { "height": 19 } を設定します。
4. セクションのオプション - options.custom.name、collapsed、および color.predefined: "SECTION_PREDEFINED_COLOR_UNSPECIFIED" を含めます。
5. フィルター - フェーズ 2 のスライス対象ディメンションごとに 1 つ設定します。デフォルトの演算子は equals、values はユーザーが入力できるよう空にします。環境の除外には notEquals を使用します（references/widget-templates.md を参照してください）。
6. relativeTimeFrame - ユーザーが別の値を指定していない限り、デフォルトは "172800s"（48 時間）です。

クエリ構文については references/query-syntax.md を参照してください。クエリ言語の全容については、references/dataprime-reference.md と references/promql-guidelines.md を読み込んでください。

---

フェーズ 5：cx CLI ですべてのクエリをライブ検証する

フェーズ 8 に進む前に、ドラフトに含まれるすべての PromQL および DataPrime クエリを cx で正常に実行できることを確認します。これにより、存在しないメトリクス名、誤記されたフィールドパス、形式の不正なパイプラインを検出できます。

Frequent と Archive の違い（JSON での内容／選択時期／指定場所）

内容：

• Frequent（TIER_FREQUENT_SEARCH）：最近のログ／スパンを高速に検索するためのホットティアです。
• Archive（TIER_ARCHIVE）：古いログ／スパンを長期保存するためのコールドティアです。

選択基準：

• オンコール対応や最近の調査（数時間／数日）には、Frequent を選択します。
• 長期間を対象にする場合（数週間／数か月）、または時間範囲がホットティアの保持期間を超える場合は、Archive を選択します。

2 つの言語は、異なる時間範囲で検証します。

• PromQL：relativeTimeFrame を $RANGE トークン（例：172800s の場合は 48h）に対応付け、CLI 呼び出し用に ${__range} を [$RANGE] に置換してから、Phase 6 の前に JSON 内で ${__range} に戻します。範囲ベクトルは時間範囲に依存するため、ダッシュボードで評価される内容と一致する条件で確認する必要があります。
• DataPrime：固定の短い時間範囲（now-15m → now、--limit 1）で検証します。目的は、ダッシュボードの時間範囲でデータが存在するかではなく、構文／フィールド／パイプラインを検証することです。短い時間範囲のほうが速く、失敗を明確に判定できます。

手順の全容（CLI 呼び出し、$RANGE の対応表、再試行回数、失敗時の動作）：references/verification.md。

クエリが再試行回数の上限内に通らない場合は、CLI エラーをそのままユーザーに提示してください。壊れたウィジェットを納品してはいけません。

---

Phase 6：構造を自己検証する

最終 JSON に対して以下のチェックリストを実行します。いずれかの項目に失敗した場合は、Phase 7 の前に修正して再確認します。

クエリ構文（ダッシュボード固有）

• メトリクスウィジェットのすべての PromQL 範囲ベクトルで [${__range}] を使用します。[$__range] や [5m] は使用しません（パネルが意図的にスライディングウィンドウになっている場合を除きます）。
• 単一値ウィジェット（ゲージ、円グラフ、動的テーブル）では、promqlQueryType を PROM_QL_QUERY_TYPE_INSTANT にします。lineChart では省略します。
• DataPrime のログクエリでは、$d.<field>／$l.applicationname／引用符で囲まない重大度列挙値を使用します（ルールの全容：references/dataprime-reference.md）。
• すべての DataPrime ウィジェットクエリは source logs または source spans で始まります（ダッシュボードウィジェットでは source プレフィックスが必要です。Phase 5 の検証では、パイプラインを cx logs／cx spans に渡す前にこれを取り除きます）。
• 成功率の分母を clamp_min(..., 1) でラップします。
• ヒストグラムクエリでは、正しいサフィックス（_sum、_count、_bucket）を使用します。
• ダッシュボードレベルの filters がなくても、ウィジェットクエリが有効です。Coralogix はレンダリング時にフィルターを挿入します。

構造

• 各セクションに id.value、rows、options.custom が含まれています。
• 各行に id.value、appearance.height、widgets が含まれています。
• 各ウィジェットに一意の id.value があり、gauge／pieChart／lineChart／dynamic のいずれか 1 つだけを含む definition があります。
• すべてのゲージに数値の min と max があり、min < max になっています。
• 成功率ゲージでは、高い値を緑で示す thresholdType: "THRESHOLD_TYPE_ABSOLUTE" を使用します。エラー／DLQ ゲージでは、高い値を赤で示します。
• メトリクスの「Total」／「stat」ウィジェットは gauge としてエンコードします。ログ、スパン、または DataPrime の合計値は、stat の可視化を使う dynamic ウィジェットにします。
• トップレベルの filters に Phase 2 の各スライスディメンションが含まれています。
• すべての ID は新たに生成された UUID で、ドキュメント内で一意です。
• 各 queryDisplaySettings[].queryId は、同じウィジェット内の queryDefinitions[] エントリーの id と一致します。cx dashboards check では不一致が許容されますが、その場合ウィジェットは空で表示されます。

内容

• ダッシュボード名が説明的です（"<Service> - <Purpose>"）。
• ウィジェットのタイトルが簡潔でわかりやすく、クエリの計算内容と一致しています。
• ユーザーから別途指定がない限り、ログ／エラーのセクションは collapsed: true です。

---

フェーズ 7：cx dashboards check によるサーバー側検証

フェーズ 6 では手作業で構造上の問題を検出しました。このフェーズでは、ダッシュボード全体を Coralogix Dashboard Service の厳格なバリデーター（CheckDashboard）にかけます。これは、書き込み時に create／replace が適用する検証と同じもので、さらにすべての PromQL／DataPrime クエリをコンパイルし、変数とフィルターに必須の ID が設定されていることも確認します。

1. cx dashboards check --from-file /tmp/cx-dashboard-<slug>.json を実行します。
2. コマンドが 0 以外の終了コードを返した場合、出力には severity、location（ダッシュボード内の RFC 6901 JSON Pointer。例：/sections/0/rows/1/widgets/2）、および message を含む問題が一覧表示されます。JSON 内の各問題を修正し（フェーズ 4 に戻ります）、クエリを変更した場合はフェーズ 5 を再実行してから、このフェーズを再実行します。
3. check が 0 を返したら（テキスト出力：Dashboard is valid (no issues)）、フェーズ 8 に進みます。

check は読み取り専用で、ダッシュボードを保存することはありません。警告（SEVERITY_WARNING）は表示されますが、ゲートの失敗にはなりません。エラー（SEVERITY_ERROR）のみが 0 以外の終了コードを発生させます。複数プロファイルへのファンアウトでは、エラーを返すプロファイルが 1 つでもあるとコマンドは失敗します。

---

フェーズ 8：cx dashboards create によるデプロイ

ユーザーに Coralogix の UI へ JSON を貼り付けるよう案内せず、直接デプロイしてください。

1. フォルダーを一覧表示します：cx dashboards folders list -o json。
2. 最適なフォルダーを提案します（チーム、製品領域、またはサービス名のフォルダー）。適切なフォルダーがなければ、ルートをデフォルトとして使用します（--folder を省略）。
3. 検証済みの JSON を一時ファイルに書き込み、cx dashboards create --from-file /tmp/cx-dashboard-<slug>.json --folder <id> を実行します。CLI が requestId エンベロープを生成し、作成されたダッシュボード ID を出力します。

手順の詳細（フォルダー選択の UX、コマンドのテンプレート、冪等性に関する注意）：references/deploy.md。

失敗した場合：CLI のエラーをそのまま表示し、フェーズ 5 に戻ります。最もよくある原因は、ローカルでは解析できるクエリがライブ API に拒否されることです。

---

フェーズ 9：ダッシュボードのリンクを共有する

ユーザーがクリック可能なダッシュボードへのリンクを受け取るまでは、ワークフローは完了していません。ID だけを出力すると、ユーザーが Coralogix の UI を手作業で操作する必要があり、デプロイを自動化する意味がなくなります。

フェーズ 8 の成功後、cx dashboards create が標準エラー出力に表示する View in Coralogix: <url> の行を取得し（省略される場合については references/deploy.md §「リンクの共有」を参照）、以下の出力テンプレートを出力します。リンクテキストにはダッシュボードの名前を使用します。ユーザーがクリックするのはこのテキストです。

cx dashboards catalog で見つけたダッシュボードへのリンクは（作成したばかりのダッシュボードとは）方法が異なります。catalog が出力するリンクはカタログページへの 1 つだけで、ダッシュボードごとのリンクはありません。その一覧から特定のダッシュボードにリンクするには、<base>/dashboards/<dashboard_id> を組み立てます。<base> には、このセッション中にいずれかの cx dashboards コマンドが出力した View in Coralogix: <base>/... の行ですでに確認されているコンソール URL を使用してください。<base> を自分で捏造したり、そのような行がまだ出力されていない場合に作り出したりしてはいけません。

---

ユーザー向け出力形式

cx dashboards create が View in Coralogix: リンクを出力した場合：

## Plan
<the approved Phase 3 plan>

## Verification
- PromQL queries verified: <N>/<N>
- DataPrime queries verified: <N>/<N>

## Deployed
- Dashboard: **[<Name>](<url from the View in Coralogix line>)**
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Open it: [<Name>](<url from the View in Coralogix line>)

Adjust filter values (e.g. `account_id`) after opening it.

cx dashboards create が View in Coralogix: の行を出力しなかった場合（プロファイルのコンソールリンクを解決できず、console_url のオーバーライドも設定されていない場合）は、リンクを完全に省略してください。URL を捏造してはいけません。代わりに、以下のテンプレートを使用します：

## Plan
<the approved Phase 3 plan>

## Verification
- PromQL queries verified: <N>/<N>
- DataPrime queries verified: <N>/<N>

## Deployed
- Dashboard: **<Name>** (open via the Coralogix UI; ID `<id>`)
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Adjust filter values (e.g. `account_id`) after opening it.

---

参考資料

• ダッシュボードクエリの注意点と相互参照：references/query-syntax.md
• ウィジェット JSON テンプレート：references/widget-templates.md
• ライブ検証の手順：references/verification.md
• デプロイ手順：references/deploy.md
• DataPrime 言語リファレンス：references/dataprime-reference.md
• PromQL リファレンス：references/promql-guidelines.md
• ログクエリのパターン：references/logs-querying.md
• スパンのクエリパターン：references/spans-querying.md
• DataPrime のインラインヘルプ：cx dataprime list、cx dataprime show <command>
• Coralogix カスタムダッシュボードのドキュメント：https://www.coralogix.com/docs/user-guides/custom-dashboards/introduction/

関連スキル

• cx-observability-setup - 完全なモニタリング設定ワークフロー（ビュー、Webhook、通知、インテグレーション）
• cx-slos - ダッシュボードに表示する、SLO に紐づいた信頼性目標
• cx-cases - ダッシュボードで監視するサービスに対して起票されたケースのトリアージ
• cx-telemetry-querying - ダッシュボードの作成前に、適切なテレメトリーシグナルを見つける