cloud-trace-querying
Query Cloud Trace spans, filter by latency thresholds or error status, correlate distributed traces with Cloud Logging, and diagnose latency bottlenecks across Google Cloud services
Install / Use
npx skills add google/skills --skill cloud-trace-queryingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
OperationsSupported Platforms
Our assessment of cloud-trace-querying
cloud-trace-querying scores 97/100 on our quality scale, 44th of 763 Operations skills we index (top 6%).
Its SKILL.md is 6.7 KB long, well organised into 18 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
With 20,340 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so cloud-trace-querying is actively maintained.
- Our last check on 2026-11-14 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-08. Automated pattern scan on 2026-10-08. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
cloud-trace-querying compared with similar skills
All 4 of these similar skills score higher than cloud-trace-querying; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| cloud-trace-querying (this skill)by google | 97 | 20.3k | 2mo ago | SKILL.md |
| algorithmic-artby anthropics | 100 | 177.9k | 2mo ago | SKILL.md |
| pptxby anthropics | 100 | 177.9k | 2mo ago | SKILL.md |
| prospectingby coreyhaines31 | 100 | 60.1k | 11d ago | SKILL.md |
| ad-creativeby coreyhaines31 | 100 | 60.1k | 11d ago | SKILL.md |
Frequently asked questions
- How do I install cloud-trace-querying?
- Run
npx skills add google/skills --skill cloud-trace-querying. The install tabs above show the steps for each supported agent. - Which AI agents does cloud-trace-querying work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is cloud-trace-querying safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is cloud-trace-querying still maintained?
- The repository was last updated about 2 months ago, so cloud-trace-querying is actively maintained.
Skill content
View source on GitHubname: cloud-trace-querying metadata: version: "1.0.0" category: CloudObservabilityAndMonitoring description: >- Query Cloud Trace spans, filter by latency thresholds or error status, correlate distributed traces with Cloud Logging, and diagnose latency bottlenecks across Google Cloud services. Use when investigating slow requests, analyzing trace hierarchies, or resolving latency regressions. Do NOT use for querying non-GCP telemetry or database query optimization outside Cloud Trace.
Cloud Trace Querying Skill (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.
Prerequisites & Setup
- Google Cloud SDK: Verify
gcloudis installed (Installation Guide). - Authentication: Authenticate CLI and application default credentials:
gcloud auth login && gcloud auth application-default login - Project & Billing: Identify the target
<PROJECT_ID>(from the user's prompt or viabash scripts/get_trace_project/run.sh), ensure an active billing account is attached, and configure the project if not already set:gcloud config set project <PROJECT_ID> - API Enablement: Verify Cloud Trace and Cloud Logging APIs are enabled:
gcloud services enable cloudtrace.googleapis.com logging.googleapis.com
Quickstart Workflows
1. Identify Google Cloud Project 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 scripts/get_trace_project/run.sh
2. Search Traces (Latency & Errors)
To find traces matching specific criteria, such as a root span of /v1/booking/book with a duration of at least 1.5s:
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.
3. Fetch Entire Trace Hierarchy
To view all spans and status codes/labels within a trace:
bash scripts/fetch_entire_trace/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>'
4. Fetch Correlated Application Logs
To retrieve application log entries correlated with a trace ID:
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.
5. Fetch Specific Trace Span
To inspect attributes and metadata of a single span within a trace:
bash scripts/fetch_trace_span/run.sh --trace-id '<TRACE_ID>' --span-id '<SPAN_ID>' --project '<PROJECT_ID>'
6. Generate Cloud Console Deep Links
To generate direct Cloud Console URLs for browser inspection of traces or correlated logs:
bash scripts/generate_links/run.sh --trace-id '<TRACE_ID>' --project '<PROJECT_ID>' [--span-id '<SPAN_ID>']
7. Format Output
- Terminal / CLI: Render span trees as indented ASCII timelines using
|--. - UI Presentation: Render as A2UI JSON graph structures when requested for UI.
8. Upstream Service Error Handling
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.
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
Semantic Conventions
- Conventions Overview
- OpenTelemetry Core
- OpenTelemetry HTTP
- OpenTelemetry gRPC & RPC
- OpenTelemetry GenAI
- GCP App Hub & Service Conventions
- GCP Legacy Labels
Concepts & Architecture
- Observability Scopes
- Distributed Traces Concept
- Spans Concept
- Logs-to-Trace Correlation
- Knowledge Overview
Templates & Assets
Official Documentation Links
Related Skills
algorithmic-art
177.9kCreating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems.
pptx
177.9kUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an em…
prospecting
60.1kWhen the user wants to find and qualify prospects for outbound, or asks who to target first, which signal to prioritize, or where to spot buyers with the problem: buying signals, enrichment, verification, account research.
ad-creative
60.1kWhen the user wants to write or judge ad creative, or asks which ad, hook, or angle to run or kill: headlines, primary text, and variations for Google, Meta, LinkedIn, and TikTok, fresh angles when creative fatigues. Test hypotheses name the metric, comparison, and expected direction.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
