How to use the Cloud Trace Querying agent skill

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file and supporting files. When a skill is installed, the agent reads its instructions and uses them for tasks that match its description. This skill equips the agent with standard Cloud Trace query patterns, diagnostic workflows for latency and errors, and scripts that fetch and inspect trace hierarchies.

• Search traces by root span and latency threshold, or by error status.
• Fetch the entire span tree for one trace ID, or a single span.
• Fetch application log entries correlated with a trace ID from Cloud Logging.
• Generate Cloud Console links for a trace or span.
• Present span trees as indented ASCII timelines, or as A2UI JSON graph structures when a UI is needed.

Install the skill from the ZIP or upload it

Download the ZIP for google/skills / skills/cloud/cloud-trace-querying from the directory page and unzip it. For a personal install, place the folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder. In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

After installing, the folder should contain SKILL.md along with its assets and scripts. The skill is licensed under Apache-2.0.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

Set up Google Cloud access first

Every command the skill runs needs a working Google Cloud setup. The SKILL.md walks the agent through these prerequisites, but you should confirm them yourself before starting. You need the Google Cloud SDK (gcloud), authentication for the CLI and application default credentials, a project with billing enabled, and the Cloud Trace and Cloud Logging APIs enabled. Your account also needs permission to read traces and logs in the target project.

• Verify gcloud is installed (the SDK installation guide is linked from the skill).
• Authenticate with gcloud auth login and gcloud auth application-default login.
• Set the project with gcloud config set project <PROJECT_ID>.
• Enable the APIs with gcloud services enable cloudtrace.googleapis.com logging.googleapis.com.

Trigger the skill with natural requests

You do not need to type script names. Describe the problem in plain language and name the project and, if you have it, the route or trace ID. The skill's description tells the agent to use it when investigating slow requests, analysing trace hierarchies, or resolving latency regressions.

If you do not give a project ID, the agent is instructed to find one by running the project lookup script. Name the project yourself when you can, because it avoids a lookup step.

• Why is the /v1/booking/book route slow in project my-project today?
• Find traces for /v1/booking/book that took at least 1.5 seconds.
• Here is trace ID <TRACE_ID>. Show me the full span tree and any error logs.
• Give me Cloud Console links for this trace.

Example: search for slow traces and drill in

The search script takes a filter. The example below finds traces whose root span is /v1/booking/book with a duration of at least 1.5 seconds. The filter is required; to list traces without narrowing, the source says to pass an empty filter or root: alone.

The output is JSON. Each cluster's examples array lists sample traces with trace_id, duration_seconds, span count, and error status. Copy a trace_id into the next step to fetch the full hierarchy, then fetch correlated logs for that same trace.

• Filter syntax uses latency:<duration>, for example latency:1.5s for 1.5 seconds or more. This matches "Span duration" in Trace Explorer.
• Other filter forms in the skill include root:, +span:, and error:true.
• Look for severity: "ERROR" in correlated log entries when diagnosing failures.

Read the output: trees, logs and links

Once you have a trace ID, the agent can fetch every span and its status with the entire-trace script. Correlated logs are fetched separately using the same trace ID. Be aware that the log query searches the default _Default log scope, so an empty result can mean there are no matching entries, the caller lacks permission, or the entries live in a log view outside that scope.

Terminal output uses indented |-- trees. For a UI, ask for A2UI JSON. The skill also ships example templates for single spans, trace charts, trace flows and heat maps in both formats.

• Fetch the full trace: bash scripts/fetch_entire_trace/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'
• Fetch correlated logs: bash scripts/fetch_related_logs/run.sh --trace-id '<TRACE_ID>' --trace-projects '<PROJECT_ID>'
• Fetch one span: bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'
• Generate links: bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'

Safety notes before you approve commands

This skill runs scripts and uses the network. Its instructions tell the agent to execute bash tools directly and report the exact results rather than only describing them. Read each command before you approve it, especially when the agent is working in a project with other sensitive data. The skill also tells the agent to report upstream API errors such as 500 or 503 responses instead of debugging local libraries, so an outage will show up as a report, not a fix.

The skill asks the agent to read its attribution reference before running gcloud, REST or MCP commands, and to prefix terminal gcloud calls with a CLOUDSDK_METRICS_REQUEST_ATTRIBUTION setting. Expect to see that prefix in commands you review.

• Review every bash command before approving it.
• Use a project you are allowed to read traces and logs from.
• Do not expect non-GCP telemetry or general database tuning from this skill; it says it does not cover them.