Back to Details

cloud-trace-querying

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cloud Trace Querying Skill (
cloud-trace-querying
)

Cloud Trace 查询技能 (
cloud-trace-querying
)

This skill equips the agent to interact with Cloud Trace by providing standard query patterns, diagnostic workflows for latency and errors, and tools to fetch and inspect trace hierarchies.
[!IMPORTANT] AUTONOMOUS TOOL EXECUTION MANDATE: You MUST execute the tool scripts directly in bash to query telemetry. Do NOT just describe query strings or write Python scripts. Run the provided bash tools directly and report the exact results.
本技能为Agent提供标准查询模式、延迟与错误诊断工作流以及获取和检查追踪层级的工具，使其能够与Cloud Trace交互。
[!IMPORTANT] 自主工具执行要求： 你必须直接在bash中执行工具脚本来查询遥测数据。不得仅描述查询字符串或编写Python脚本。请直接运行提供的bash工具并报告准确结果。

Prerequisites & Setup

前提条件与设置

  1. Google Cloud SDK: Verify 
    gcloud
    is installed (Installation Guide).
  2. Authentication: Authenticate CLI and application default credentials:
    bash
    gcloud auth login && gcloud auth application-default login
  3. Project & Billing: Identify the target 
    <PROJECT_ID>
    (from the user's prompt or via 
    bash scripts/get_trace_project/run.sh
    ), ensure an active billing account is attached, and configure the project if not already set:
    bash
    gcloud config set project <PROJECT_ID>
  4. API Enablement: Verify Cloud Trace and Cloud Logging APIs are enabled:
    bash
    gcloud services enable cloudtrace.googleapis.com logging.googleapis.com
  1. Google Cloud SDK：确认已安装
    gcloud
    （安装指南）。
  2. 身份验证：对CLI和应用程序默认凭据进行身份验证：
    bash
    gcloud auth login && gcloud auth application-default login
  3. 项目与计费：确定目标
    <PROJECT_ID>
    （从用户提示中获取或通过
    bash scripts/get_trace_project/run.sh
    获取），确保已绑定有效的计费账户，若尚未配置项目请执行以下命令：
    bash
    gcloud config set project <PROJECT_ID>
  4. API启用：确认已启用Cloud Trace和Cloud Logging API：
    bash
    gcloud services enable cloudtrace.googleapis.com logging.googleapis.com

Quickstart Workflows

快速入门工作流

1. Identify Google Cloud Project ID

1. 确定Google Cloud项目ID

If the user specified a Google Cloud project ID in their prompt, use it.
If they did not, ALWAYS determine the Google Cloud project ID by running:
bash
bash scripts/get_trace_project/run.sh
如果用户在提示中指定了Google Cloud项目ID，请直接使用。
如果未指定，请始终通过运行以下命令确定Google Cloud项目ID：
bash
bash scripts/get_trace_project/run.sh

2. Search Traces (Latency & Errors)

2. 搜索追踪（延迟与错误）

To find traces matching specific criteria, such as a root span of 
/v1/booking/book
with a duration of at least 1.5s:
bash
bash scripts/search_traces/run.sh --filter 'root:/v1/booking/book latency:1.5s' --projects '<PROJECT_ID>'
Note: 
--filter
is required. To list traces without specific filtering, pass 
--filter ''
or 
--filter 'root:'
. Filter syntax: The Cloud Trace API uses 
latency:<duration>
(such as 
latency:1.5s
for duration >= 1.5s), which corresponds to "Span duration" in Trace Explorer. The script outputs JSON where each cluster's 
examples
array contains sample trace objects with 
trace_id
, 
duration_seconds
, span count, and error status.
要查找符合特定条件的追踪，例如根span为
/v1/booking/book
且持续时间至少为1.5秒的追踪：
bash
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.5秒），对应Trace Explorer中的“Span持续时间”。 脚本输出JSON格式，每个集群的
examples
数组包含示例追踪对象，其中包含
trace_id
、
duration_seconds
、span数量和错误状态。

3. Fetch Entire Trace Hierarchy

3. 获取完整追踪层级

To view all spans and status codes/labels within a trace:
bash
bash scripts/fetch_entire_trace/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'
要查看追踪内的所有span和状态码/标签：
bash
bash scripts/fetch_entire_trace/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'

4. Fetch Correlated Application Logs

4. 获取关联的应用日志

To retrieve application log entries correlated with a trace ID:
bash
bash scripts/fetch_related_logs/run.sh --trace-id '<TRACE_ID>' --trace-projects '<PROJECT_ID>'
Application log entries are useful when inspecting stack traces, exception messages, and log events emitted during span execution. When diagnosing errors or service crashes, inspect the returned log entries for 
severity: "ERROR"
to confirm root causes or uncover unhandled exceptions. Note: 
fetch_related_logs
queries the default log scope (
_Default
), searching across configured log views in the target project. An empty response can occur if: (1) no log entries match the criteria, (2) the caller lacks IAM permissions to view the matching entries, or (3) matching entries reside in log views outside the searched log scope.
要检索与追踪ID关联的应用日志条目：
bash
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. Fetch Specific Trace Span

5. 获取特定追踪span

To inspect attributes and metadata of a single span within a trace:
bash
bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'
要检查追踪中单个span的属性和元数据：
bash
bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'

6. Generate Cloud Console Deep Links

6. 生成Cloud Console深层链接

To generate direct Cloud Console URLs for browser inspection of traces or correlated logs:
bash
bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>' [--span-id '<SPAN_ID>']
要生成直接的Cloud Console URL，以便在浏览器中查看追踪或关联日志：
bash
bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>' [--span-id '<SPAN_ID>']

7. Format Output

7. 输出格式

  • Terminal / CLI: Render span trees as indented ASCII timelines using 
    |--
    .
  • UI Presentation: Render as A2UI JSON graph structures when requested for UI.
  • 终端 / CLI：使用
    |--
    将span树渲染为带缩进的ASCII时间线。
  • UI展示：当需要UI展示时，渲染为A2UI JSON图结构。

8. Upstream Service Error Handling

8. 上游服务错误处理

If the Cloud Trace API or Cloud Logging API returns an upstream HTTP service error (such as 
500 Internal Server Error
, 
503 Service Unavailable
, or 
GoogleAPICallError
), report the upstream service outage directly to the user. Do not attempt to inspect virtual environments, modify internal scripts, or debug local libraries.
如果Cloud Trace API或Cloud Logging API返回上游HTTP服务错误（例如
500 Internal Server Error
、
503 Service Unavailable
或
GoogleAPICallError
），请直接向用户报告上游服务中断。请勿尝试检查虚拟环境、修改内部脚本或调试本地库。

Reference Documentation

参考文档

  • Master Index: Reference Documentation Index
  • 总索引：参考文档索引

Operational Workflows

操作工作流

  • Troubleshoot Latency Workflow
  • Correlated Logs Workflow
  • Trace Querying Decision Tree
  • Console Deep Links
  • Workflows Overview
  • 延迟排查工作流
  • 关联日志工作流
  • 追踪查询决策树
  • 控制台深层链接
  • 工作流概览

Query Syntax & Tools

查询语法与工具

  • Filter Syntax (
    root:
    , 
    latency:
    , 
    +span:
    , 
    error:true
    )
  • API Limits and Constraints
  • Observability Analytics (BigQuery SQL)
  • Cloud Trace MCP Tools
  • 过滤语法（
    root:
    、
    latency:
    、
    +span:
    、
    error:true
    ）
  • API限制与约束
  • 可观测性分析（BigQuery SQL）
  • Cloud Trace MCP工具

Semantic Conventions

语义约定

  • Conventions Overview
  • OpenTelemetry Core
  • OpenTelemetry HTTP
  • OpenTelemetry gRPC & RPC
  • OpenTelemetry GenAI
  • GCP App Hub & Service Conventions
  • GCP Legacy Labels
  • 约定概览
  • OpenTelemetry核心
  • OpenTelemetry HTTP
  • OpenTelemetry gRPC与RPC
  • OpenTelemetry GenAI
  • GCP App Hub与服务约定
  • GCP旧版标签

Concepts & Architecture

概念与架构

  • Observability Scopes
  • Distributed Traces Concept
  • Spans Concept
  • Logs-to-Trace Correlation
  • Knowledge Overview
  • 可观测性范围
  • 分布式追踪概念
  • Span概念
  • 日志与追踪关联
  • 知识概览

Templates & Assets

模板与资源

  • ASCII Formatting Templates
  • A2UI Formatting Templates
  • Query Scenarios
  • ASCII格式化模板
  • A2UI格式化模板
  • 查询场景

Official Documentation Links

官方文档链接