cx-create-dashboard

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 get <dashboard-id> -o json > dashboard.json
# Edit dashboard.json (change name, modify widgets, etc.)
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: Deploy via `cx dashboards create`
- [ ] Phase 8: Share the dashboard link with the user

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

フェーズ 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 の参照箇所を grep で検索します。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 件のテーブル、直近のエラー、エンティティごとの一覧	dataTable

ユーザーから求められない限り、ほかのウィジェットタイプは使用しないでください。

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 でライブ検証する

フェーズ 7 に進む前に、ドラフト内の PromQL クエリと DataPrime クエリをすべて cx で正常に実行する必要があります。これにより、実在しないメトリクス名、フィールドパスの入力ミス、形式が不正なパイプラインを検出できます。

Frequent と Archive（概要／選択基準／JSON での指定場所）

概要：

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

選択基準：

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

2 つの言語は、異なる期間を使って検証します。

• PromQL：relativeTimeFrame を $RANGE トークンに変換します（例：172800s の場合は 48h）。CLI 呼び出しでは ${__range} を [$RANGE] に置換し、フェーズ 6 の前に JSON 内で ${__range} に戻します。レンジベクトルは期間に依存するため、ダッシュボードで評価される期間に合わせて検証する必要があります。
• DataPrime：固定の短い期間（now-15m → now、--limit 1）で検証します。目的は構文／フィールド／パイプラインの検証であり、ダッシュボードの期間内にデータが存在するかどうかの確認ではありません。短い期間を使うことで、検証が速くなり、失敗の判定も明確になります。

手順の全容（CLI の呼び出し、$RANGE の対応表、再試行回数の上限、失敗時の状況）については、references/verification.md を参照してください。

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

---

フェーズ 6：構造を自己検証する

最終 JSON を次のチェックリストに照らして確認します。項目に不備があれば、フェーズ 7 に進む前に修正して再確認してください。

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

• メトリクスウィジェット内の PromQL レンジベクトルはすべて [${__range}] を使用しています。[$__range] や [5m] は使用しません（パネルが意図的にスライディングウィンドウを使う場合を除く）。
• 単一値ウィジェット（ゲージ、円グラフ、データテーブル）の promqlQueryType は PROM_QL_QUERY_TYPE_INSTANT です。lineChart では省略します。
• DataPrime のログクエリでは $d.message／$l.applicationname／引用符で囲まない重大度の列挙値を使用しています（詳細なルールは references/dataprime-reference.md を参照）。
• DataPrime の各ウィジェットクエリは source logs または source spans で始まっています（ダッシュボードのウィジェットではソースプレフィックスが必要です。フェーズ 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／dataTable のいずれか1つだけを含む definition がある。
• 成功率ゲージでは、thresholdType: "THRESHOLD_TYPE_ABSOLUTE" を使用し、高い値を緑色にする。エラー／DLQ ゲージでは、高い値を赤色にする。
• 「Total」／「stat」ウィジェットは stat 型ではなく、gauge として記述する。
• トップレベルの filters に、Phase 2 で指定した各スライスディメンションが含まれている。
• すべての ID は新たに生成した UUID であり、ドキュメント内で重複していない。

内容

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

---

フェーズ 7：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 に拒否されることです。

---

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

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

フェーズ 7 が成功したら、cx dashboards create が返したダッシュボードの id を取得し、references/deploy.md の「リンクを共有する」にあるリージョンから Web アプリのホストへのマッピングを使って URL を作成し、以下の出力テンプレートを出力します。リンクテキストにはダッシュボードの名前を指定します。ユーザーがクリックするのはその名前です。

---

ユーザー向けの出力形式

Web アプリのホストを特定できる場合（組み込みリージョン、または api.<host> の規則に従った Custom エンドポイント）：

## Plan
<the approved Phase 3 plan>

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

## Deployed
- Dashboard: **[<Name>](https://<region>.app.coralogix.com/#/dashboards/<id>)**
- ID: `<id>`
- Folder: `<folder name or "root">`
- Profile: `<cx profile>`

Open it: [<Name>](https://<region>.app.coralogix.com/#/dashboards/<id>)

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

Web アプリのホストを特定できない場合（api.<host> に一致しないカスタムエンドポイント）は、リンクを省略してください。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-incident-management - SLO とアラートに連携したダッシュボード、インシデントのトリアージ
• cx-telemetry-querying - ダッシュボードを作成する前に、適切なテレメトリーシグナルを見つける