cx-telemetry-querying

テレメトリクエリスキル

テレメトリデータで答えられる可能性がある調査、デバッグ、データに関する質問には、このスキルをエントリーポイントとして使用してください。関連するシグナルがどこにあるか（メトリクス、ログ、トレース、RUM）を判断し、クエリを実行する前にどのリファレンスファイルを読み込むべきかを案内します。

リファレンスの読み込み

クエリを実行する前に、選択した柱に対応するリファレンスファイルを読み込んでください。

柱	読み込むファイル
ログ	references/dataprime-reference.md + references/logs-querying.md
スパン／トレース	references/dataprime-reference.md + references/spans-querying.md
メトリクス	references/promql-guidelines.md + references/metrics-querying.md
RUM（フロントエンド）	references/dataprime-reference.md + references/rum-querying.md + references/rum-fields.md
DataPrime の構文のみ	references/dataprime-reference.md

---

安全性

すべてのクエリコマンド（cx logs、cx spans、cx metrics、cx dataprime、cx search-fields）は読み取り専用で、--read-only モードで動作します。データを変更することはなく、--yes を指定せずに自由に実行できます。

---

クイックルーティングガイド

どの柱を最初に選ぶべきかが明らかな場合は、次の表を使用してください。

質問の種類	第一候補	フォールバック
UI の動作、ページ読み込み、フロントエンドのエラー	RUM	トレース（バックエンドに関する場合）
エンドポイントのレイテンシ、スループット、エラー率	メトリクス	トレース（リクエストごとの詳細を確認する場合）
サービス間の依存関係、リクエストフロー	トレース	ログ（デバッグ出力を確認する場合）
特定のエラーメッセージ、スタックトレース	ログ	トレース（リクエストのコンテキストを確認する場合）
インフラストラクチャの健全性（CPU、メモリ、ディスク）	メトリクス	-
ビジネスイベント（購入、登録）	ケースによります。「探索ワークフロー」を参照	-

あいまいな質問（例：「先週、ユーザーはどれくらいお金を使いましたか？」）では、シグナルがどの柱に存在するかは分かりません。以下の探索ワークフローに従ってください。

---

探索ワークフロー

答えが複数の柱に存在する可能性がある場合は、最適なデータソースを見つけるために、並行して探索を実行してください。

ステップ 1：メトリクスを検索する

関連するメトリクスが存在するか確認します。

cx metrics search --name '*transaction*'
cx metrics search --name '*payment*'
cx metrics search --name '*revenue*'
cx metrics search --description "total purchase amount"

一致するメトリクスが見つかった場合は、references/promql-guidelines.md と references/metrics-querying.md を読み込み、続行してください。

ステップ 2：ログとスパンのフィールドを検索する

セマンティックフィールド検索を使用して、関連する DataPrime のパスを見つけます。

cx search-fields "transaction amount" --dataset logs
cx search-fields "payment total" --dataset spans
cx search-fields "purchase value" --dataset logs --limit 10

データに含まれるはずの具体的な値が分かっているものの、どのフィールドに格納されているか分からない場合は、代わりに値検索を使用してください。一致したフィールドキーとサンプル値が返されるため、フィールドの型（文字列、数値、列挙型など）を推測することもできます。

cx search-fields "payment_failed" -s value --dataset logs
cx search-fields "grpc.status.UNAVAILABLE" -s value --dataset spans
cx search-fields "eu-west-1" -s value --dataset all

要件： cx search-fields を使用するには、アクティブなプロファイルで Coralogix API キーまたは OAuth が必要です。認証情報がない場合は、ユーザーに cx profiles add <name> を実行するよう依頼してください。

一致するフィールドが見つかった場合：

• ログの場合：references/dataprime-reference.md と references/logs-querying.md を読み込みます
• スパンの場合：references/dataprime-reference.md と references/spans-querying.md を読み込みます

ステップ 3：コードベースを検索する

探索結果があいまいな場合や、メトリクス／フィールドが実際に何を表しているかを検証する必要がある場合は、コードベースを検索してください。

• メトリクスの登録コードを探します（例：prometheus.NewCounter、metrics.record）
• フィールドを出力するログ文を探します（例：logger.info("transaction", ...)）
• スパンの属性を探します（例：span.setAttribute("purchase.amount", ...)）

これにより、セマンティックな意味を確認し、適切な柱を選びやすくなります。

ステップ 4：選択してクエリを実行する

探索結果に基づいて、最も明確なシグナルがある柱を選び、リファレンスファイル（リファレンスの読み込みを参照）を読み込んでから、クエリを実行してください。

---

フォールバックと切り替え

最初の方法で結果が得られない場合は、別の柱に切り替えてください。

切り替えの例：

• メトリクスが空 → トレース（リクエスト単位のデータ）またはログ（イベント記録）を試す
• ログが空 → トレース（構造化されたスパン属性）またはメトリクス（集計カウンター）を試す
• トレースが空 → ログ（テキストベースのデバッグ出力）を試す

1 回の失敗で止めないでください。データが存在しないと結論付ける前に、少なくとも 2 つの柱を試してください。

---

CLI コマンドのリファレンス

コマンド	目的	使用するタイミング
cx schema	コマンドツリー全体を JSON で出力する	利用可能なすべてのコマンドとフラグを確認する
cx metrics search --name <pattern>	名前でメトリクスを検索する	メトリクスを見つける最初の手順
cx metrics search --description <text>	意味に基づいてメトリクスを検索する	必要なものは分かっているが、名前が分からない場合
cx search-fields "<text>" --dataset logs	説明からログフィールドを見つける	ログベースの質問に向けた調査
cx search-fields "<text>" --dataset spans	説明からスパンフィールドを見つける	トレースベースの質問に向けた調査
cx search-fields "<value>" -s value --dataset logs	既知の値を含むログフィールドを見つける	値は分かっているが、どのログフィールドに格納されているか分からない場合 — 返された値からフィールドの型も確認できます
cx search-fields "<value>" -s value --dataset spans	既知の値を含むスパンフィールドを見つける	値は分かっているが、どのスパン属性に格納されているか分からない場合
cx search-fields "<value>" -s value --dataset all	ログとスパンの両方を対象に検索する	ログとスパンを一度に検索したい場合
cx spans "filter $l.serviceName == '<service>'" --limit 10	サービスでスパンを検索する	特定のサービスを調査する場合
cx dataprime list	DataPrime のコマンド／関数を一覧表示する	ログまたはスパンのクエリを作成する場合
cx dashboards search "<description>"	自然言語の説明から既存のダッシュボードを見つける	新しいダッシュボードを作成する前 — すでに存在するか確認する
cx dashboards query-search --description "<text>"	クエリがトピックを扱うダッシュボードウィジェットを見つける	トピックがすでにどのように監視されているかを確認する
cx dashboards query-search --field "<field-path>"	特定のフィールドを参照するウィジェットを見つける	既知のフィールドについて、既存の PromQL／DataPrime パターンを再利用する

---

例

例 1：ビジネス上の質問（データソースが曖昧）

質問：「先週、プラットフォーム上でユーザーはいくら使いましたか？」

進め方：

1. メトリクスを検索します：cx metrics search --name '*revenue*' と cx metrics search --name '*transaction*'
2. ログフィールドを検索します：cx search-fields "transaction amount" --dataset logs
3. スパンフィールドを検索します：cx search-fields "payment total" --dataset spans
4. payment_total_usd のようなメトリクスが存在する場合は、メトリクスのリファレンスを読み込み、範囲クエリを実行します
5. データがログにしかない場合は、ログのリファレンスを読み込み、DataPrime の集計を使用します
6. トレースに purchase.amount 属性がある場合は、スパンのリファレンスを読み込みます

例 2：レイテンシに関する質問（最初の選択肢が明確）

質問：「チェックアウトルートの平均レイテンシはどれくらいですか？」

進め方：

1. まずメトリクスを試します：cx metrics search --name '*checkout*latency*' または cx metrics search --name '*http*duration*'
2. ヒストグラムメトリクスが存在する場合は、メトリクスのリファレンスを読み込み、histogram_quantile を使用します
3. メトリクスがない場合は、トレースに切り替えます：スパンのリファレンスを読み込み、スパンの期間を集計します

例 3：フロントエンドのパフォーマンス（RUM）

質問：「ユーザーのダッシュボードページの読み込みが遅いのはなぜですか？」

進め方：

1. これは明らかに RUM に関する質問です。references/rum-querying.md + references/rum-fields.md + references/dataprime-reference.md を読み込みます
2. cx dataprime query --source rum.events '...' でウェブバイタルとページ読み込み時間をクエリします
3. RUM でバックエンド呼び出しが遅いと分かった場合は、API 呼び出しを調べるためにスパンのリファレンスへ切り替えます

例 4：エラー調査（ログ＋トレース）

質問：「決済エンドポイントでユーザーに 500 エラーが発生するのはなぜですか？」

アプローチ：

1. エラー率のメトリクスを確認します → メトリクスのリファレンスを読み込みます
2. エラーログを検索します → ログのリファレンスを読み込みます
3. 失敗したリクエストのトレースを取得します → スパンのリファレンスを読み込みます
4. 相互参照します：ログからトレース ID を見つけ、根本原因を特定するために完全なトレースを取得します

---

調査以外の対応

データをクエリしても、すべての質問に答えられるとは限りません。ユーザーの意図が調査ではなく運用に関するものであれば、適切なワークフロースキルに誘導してください：

ユーザーの意図	誘導先
コスト削減、使用状況の確認、TCO ポリシー	cx-cost-optimization
ケースのトリアージ、ページ通知を受けた人、ケースのタイムライン	cx-cases
SLO のステータス、エラーバジェット、サービスレベル目標	cx-slos
モニタリング、Webhook、通知の設定	cx-observability-setup
解析ルール、エンリッチメント、E2M の設定	cx-data-pipeline
アクセス監査、API キー、ユーザー管理	cx-platform-admin
ダッシュボードの作成または管理	cx-dashboards
既存のダッシュボードの検索	cx-search-dashboard

---

主な原則

• クエリの前にリファレンスを読み込む：リファレンスの読み込みの表を最初に確認します
• クエリの前に見つける：適切なソースを見つけるため、必ず検索／検出を実行します
• 並行して検出する：質問が曖昧な場合は、メトリクス、ログ、スパンを並行して検索します
• コードで検証する：メトリクスやフィールドが何を表すのか不明な場合は、コードベースを確認します
• 失敗したら別の方法を試す：一つの柱が空の場合は、諦める前に別の柱を試します