cloud-trace-querying

Query Cloud Trace spans, filter by latency and errors, and correlate distributed traces with logs.

23.7k|2.0k|Updated Mar 31, 2026
Ready to run
npx skills add https://github.com/google/skills --skill cloud-trace-querying-google
💬 Prompt for ChatGPT / Claude Chat▼
Please help me install this Agent Skill.
Skill: cloud-trace-querying
Source: https://github.com/google/skills/tree/main/skills/cloud/cloud-trace-querying
Command: npx skills add https://github.com/google/skills --skill cloud-trace-querying-google

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires google-cloud-trace, google-cloud-logging, google-auth, urllib3, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? This Skill eliminates the manual effort of navigating Cloud Trace Explorer and correlating telemetry across services. It provides structured query patterns and automated tools to diagnose latency bottlenecks and service failures in distributed systems without piecing together data from multiple consoles. ## Core Features & Use Cases - Latency Analysis: Search traces by duration threshold and span names to identify slow request paths across microservices. - Error Diagnosis: Filter traces by error status and correlate them with application logs to pinpoint root causes. - Span Inspection: Fetch complete trace hierarchies and individual span metadata including attributes and status codes. - Use Case: Your checkout service suddenly processes 50% slower. Use this Skill to search for traces with latency ≥ 1.5s, fetch the span hierarchy to isolate which downstream service (payment processor, inventory check) is the bottleneck, then pull correlated logs to see the exact error messages and stack traces. ## Quick Start Search for traces in your Google Cloud project with latency of at least 2 seconds to identify performance regressions.

Frequently Asked Questions about cloud-trace-querying

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I search for slow traces in Cloud Trace?▼

Use the search_traces script with a latency filter like `latency:1.5s` to find traces exceeding that duration. Combine with root span name filters (e.g., `root:/v1/checkout`) to target specific endpoints, then fetch the trace hierarchy to identify which spans consume the most time.

How can I correlate logs with a specific Cloud Trace?▼

The fetch_related_logs script queries Cloud Logging using the trace ID and optional span ID to retrieve all log entries stamped with that trace context. Logs are correlated via the `trace` and `spanId` fields in the LogEntry schema.

What filter syntax does Cloud Trace API v1 support?▼

Filters support root span matching (`root:/path`, `+root:/exact`), any span matching (`span:prefix`, `+span:exact`), latency thresholds (`latency:1.5s`), label matching (`key:value`, `+key:exact`), and error status (`error:true`). Latency requires no spaces in the duration suffix (e.g., `800ms`, `2.5s`).

Why don't I see logs when querying a trace ID?▼

Logs may reside in a different GCP project than the trace. The script resolves logging projects via Observability Scopes; if results are empty, verify IAM permissions and that log entries have `trace` and `spanId` fields populated by your instrumentation.

How do I diagnose latency in microservices using Cloud Trace?▼

Search for high-latency traces, fetch the span hierarchy to compare child span durations, and identify whether bottlenecks are sequential execution, a single slow component, or parallel fan-out delays. Inspect span attributes for HTTP status, RPC method, or database duration to narrow root cause.

What are the limits and retention periods for Cloud Trace data?▼

Trace data is retained for 30 days; queries beyond that return empty results. The v1 API returns a maximum of 1000 traces per request, and filter latency values must use `ms`, `s`, or `m` suffixes with no spaces.