mcpField
C
cloud-trace-querying

cloud-trace-querying

github.com/googleクラウド・DevOps21.6k1.0k 回インストール今日更新
リポジトリ

cloud-trace-querying について

レイテンシやエラーを調査するために Google Cloud Trace を照会するスキルです。エージェントによるトレース検索、スパン階層の確認、アプリケーションログとの関連付け、コンソールリンクや整形出力の作成を支援します。

主な機能

  1. 01フィルターによるトレース検索
  2. 02トレース階層とスパンの取得
  3. 03関連するアプリケーションログの取得
  4. 04Cloud Console リンクの生成
  5. 05スパンツリーまたは A2UI グラフの整形

活用シーン

  1. 01レイテンシしきい値超過のトレース検索
  2. 02スパン内のエラーとメタデータの確認
  3. 03トレース ID とアプリケーションログの関連付け
  4. 04トレース確認用コンソールリンクの準備

MCP 対応

ドキュメントでは Cloud Trace MCP ツールに言及しており、Cloud Trace と Cloud Logging の照会には bash スクリプトも用います。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/google/skills --skill cloud-trace-querying

インストール後、Claude Code で/cloud-trace-queryingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

assets/formatting/a2ui/single_span/
display.a2ui.json
assets/formatting/a2ui/trace_chart/
display.a2ui.json
assets/formatting/a2ui/trace_flow/
display.a2ui.json
assets/formatting/a2ui/traces_heat_map/
display.a2ui.json
assets/formatting/ascii/single_span/
display.txt
assets/formatting/ascii/trace_chart/
display.txt
assets/formatting/ascii/trace_flow/
display.txt
assets/formatting/ascii/traces_heat_map/
display.txt
assets/queries/billing_errors/
query.txt
SCENARIO.md
assets/queries/checkout_latency/
query.txt
SCENARIO.md
assets/queries/customer_spans/
query.txt
SCENARIO.md
assets/queries/prod_outliers/
query.txt
SCENARIO.md
assets/queries/slow_db/
query.txt
SCENARIO.md
references/
api-limits.md
attribution.md
concepts-span.md
concepts-trace.md
console-deep-links.md
conventions-gcp-legacy.md
conventions-gcp.md
conventions-otel-genai.md
conventions-otel-grpc.md
conventions-otel-http.md
conventions-otel.md
conventions.md

詳細

翻訳後に原文が更新されています。最新の内容は原文をご確認ください。

Cloud Trace クエリスキル（cloud-trace-querying）

このスキルは、標準的なクエリパターン、レイテンシとエラーの診断ワークフロー、およびトレース階層を取得・調査するツールを提供し、エージェントが Cloud Trace を操作できるようにします。

重要

ツールの自律実行に関する必須事項： テレメトリーをクエリするには、bash でツールスクリプトを直接実行する必要があります。 クエリ文字列を説明したり、Python スクリプトを作成したりするだけではいけません。提供されている bash ツールを直接実行し、正確な結果を報告してください。

前提条件とセットアップ

  1. Google Cloud SDK：gcloud がインストールされていることを確認します（インストールガイド）。
  2. 認証：CLI とアプリケーションのデフォルト認証情報を認証します。 
    gcloud auth login && gcloud auth application-default login
  3. プロジェクトと課金：対象の <PROJECT_ID> を特定し（ユーザーのプロンプトから、または bash scripts/get_trace_project/run.sh を実行して取得）、有効な課金アカウントが関連付けられていることを確認します。まだ設定されていない場合は、プロジェクトを設定します。 
    gcloud config set project <PROJECT_ID>
  4. API の有効化：Cloud Trace API と Cloud Logging API が有効になっていることを確認します。 
    gcloud services enable cloudtrace.googleapis.com logging.googleapis.com

クイックスタートのワークフロー

1. Google Cloud プロジェクト ID の特定

ユーザーがプロンプトで Google Cloud プロジェクト ID を指定している場合は、それを使用します。

指定していない場合は、必ず次を実行して Google Cloud プロジェクト ID を特定します。

bash scripts/get_trace_project/run.sh
2. トレースの検索（レイテンシとエラー）

たとえば、ルートスパンが /v1/booking/book で、所要時間が 1.5 秒以上のトレースなど、特定の条件に一致するトレースを検索するには、次を実行します。

bash scripts/search_traces/run.sh --filter 'root:/v1/booking/book latency:1.5s' --projects '<PROJECT_ID>'

注：--filter は必須です。特定のフィルタリングをせずにトレースを一覧表示するには、--filter '' または --filter 'root:' を指定します。 フィルタ構文：Cloud Trace API では latency:<duration>（たとえば、所要時間が 1.5 秒以上の場合は latency:1.5s）を使用します。これは Trace Explorer の「Span duration」に相当します。 このスクリプトは JSON を出力します。各クラスターの examples 配列には、trace_id、duration_seconds、スパン数、エラーステータスを含むトレースオブジェクトのサンプルが格納されます。

3. トレース階層全体の取得

トレース内のすべてのスパンとステータスコード／ラベルを表示するには、次を実行します。

bash scripts/fetch_entire_trace/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'
4. 関連するアプリケーションログの取得

トレース ID に関連付けられたアプリケーションログエントリを取得するには、次を実行します。

bash scripts/fetch_related_logs/run.sh --trace-id '<TRACE_ID>' --trace-projects '<PROJECT_ID>'

アプリケーションログエントリは、スタックトレース、例外メッセージ、スパンの実行中に出力されたログイベントを調査する際に役立ちます。エラーやサービスのクラッシュを診断する場合は、返されたログエントリで severity: "ERROR" を確認し、根本原因の特定や未処理の例外の検出に役立ててください。 注：fetch_related_logs はデフォルトのログスコープ（_Default）をクエリし、対象プロジェクトで設定されているログビューを検索します。応答が空になるのは、（1）条件に一致するログエントリがない、（2）呼び出し元に一致するエントリを閲覧する IAM 権限がない、または（3）一致するエントリが検索対象のログスコープ外のログビューにある場合です。

5. 特定のトレーススパンの取得

トレース内の単一スパンの属性とメタデータを調査するには、次を実行します。

bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'
6. Cloud Console の詳細リンクの生成

ブラウザーでトレースや関連ログを確認するための Cloud Console への直接リンクを生成するには、次を実行します。

bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>' [--span-id '<SPAN_ID>']
7. 出力の整形
  • ターミナル／CLI：スパンツリーを |-- を使ったインデント付き ASCII タイムラインとして表示します。
  • UI での表示：UI 向けに要求された場合は、A2UI JSON グラフ構造として表示します。
8. 上流サービスエラーへの対応

Cloud Trace API または Cloud Logging API が上流 HTTP サービスエラー（500 Internal Server Error、503 Service Unavailable、GoogleAPICallError など）を返した場合は、上流サービスの障害をそのままユーザーに報告してください。仮想環境を調査したり、内部スクリプトを変更したり、ローカルライブラリをデバッグしたりしないでください。

リファレンスドキュメント

運用ワークフロー
クエリ構文とツール
セマンティック規約
概念とアーキテクチャ
テンプレートとアセット

公式ドキュメントへのリンク

コメント

Markdown 対応