mcpField
C
cloud-trace-querying

cloud-trace-querying

github.com/google云与 DevOps21.6k1.0k 次安装今天更新
代码仓库

关于 cloud-trace-querying

用于查询 Google Cloud Trace、调查延迟和错误的技能。它帮助 Agent 搜索跟踪记录、检查 Span 层级、关联应用日志，并生成控制台链接或格式化输出。

主要功能

  1. 01按筛选条件搜索跟踪记录
  2. 02获取跟踪层级与 Span
  3. 03检索关联的应用日志
  4. 04生成 Cloud Console 链接
  5. 05格式化 Span 树或 A2UI 图

适用场景

  1. 01查找超过延迟阈值的跟踪记录
  2. 02检查 Span 中的错误和元数据
  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）

此技能通过提供标准查询模式、用于延迟和错误的诊断工作流，以及获取和检查跟踪层级的工具，帮助 Agent 与 Cloud Trace 交互。

重要

自主执行工具的要求： 你必须直接在 bash 中执行工具脚本来查询遥测数据。 不要只描述查询字符串或编写 Python 脚本。请直接运行提供的 bash 工具，并报告准确结果。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你必须阅读使用归属信息。对于直接在终端中执行的命令（绝不能放在生成的脚本、Terraform 或用户代码中），请在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:cloud-trace-querying)" 并将 agent-skills/1.0 (skill:cloud-trace-querying) 添加到 User-Agent 请求头。

前提条件与设置

  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 和 Cloud Logging API： 
    gcloud services enable cloudtrace.googleapis.com logging.googleapis.com

快速入门工作流

1. 确定 Google Cloud 项目 ID

如果用户在提示中指定了 Google Cloud 项目 ID，请使用该 ID。

如果没有指定，则始终通过运行以下命令确定 Google Cloud 项目 ID：

bash scripts/get_trace_project/run.sh
2. 搜索跟踪（延迟与错误）

要查找符合特定条件的跟踪，例如根 Span 为 /v1/booking/book 且持续时间至少为 1.5s 的跟踪：

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>（例如，latency:1.5s 表示持续时间 >= 1.5s），对应于 Trace Explorer 中的“Span duration”。 脚本会输出 JSON，其中每个集群的 examples 数组都包含示例跟踪对象，包含 trace_id、duration_seconds、Span 数量和错误状态。

3. 获取完整跟踪层级

要查看跟踪中的所有 Span、状态码和标签：

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>'

检查堆栈跟踪、异常消息和 Span 执行期间发出的日志事件时，应用日志条目很有用。诊断错误或服务崩溃时，请检查返回的日志条目中是否有 severity: "ERROR"，以确认根本原因或发现未处理的异常。 注意：fetch_related_logs 会查询默认日志范围（_Default），在目标项目中已配置的日志视图内进行搜索。如果返回为空，可能是因为：（1）没有符合条件的日志条目；（2）调用方缺少查看匹配条目的 IAM 权限；或（3）匹配的条目位于所搜索日志范围之外的日志视图中。

5. 获取特定跟踪 Span

要检查跟踪中单个 Span 的属性和元数据：

bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'
6. 生成 Cloud Console 深层链接

要生成可在浏览器中检查跟踪或关联日志的 Cloud Console 直达 URL：

bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>' [--span-id '<SPAN_ID>']
7. 格式化输出
  • 终端 / CLI：使用缩进的 ASCII 时间线呈现 Span 树，格式为 |--。
  • UI 呈现：如需用于 UI，则以 A2UI JSON 图结构呈现。
8. 上游服务错误处理

如果 Cloud Trace API 或 Cloud Logging API 返回上游 HTTP 服务错误（例如 500 Internal Server Error、503 Service Unavailable 或 GoogleAPICallError），请直接向用户报告上游服务中断。不要尝试检查虚拟环境、修改内部脚本或调试本地库。

参考文档

操作工作流
查询语法与工具
语义约定
概念与架构
模板与资源

官方文档链接

评论

支持 Markdown