trace-analysis

Analyze distributed traces in Grafana Tempo using TraceQL queries and span attributes.

4|Updated Jul 30, 2026
One-click install
npx skills add https://github.com/gabriellst/codm --skill trace-analysis-gabriellst
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: trace-analysis
Source: https://github.com/gabriellst/codm/tree/main/.claude/skills/trace-analysis
Command: npx skills add https://github.com/gabriellst/codm --skill trace-analysis-gabriellst

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Debugging production issues in a distributed TypeScript backend is slow when you cannot see how requests flow across routers, controllers, services, and repositories. This Skill provides the span attribute schema, TraceQL query patterns, and step-by-step workflows needed to find errors, slow operations, and broken request flows in Grafana Tempo. ## Core Features & Use Cases - Span Attribute Reference: Documents every attribute emitted by the auto-tracing utility (class.name, class.component, method.duration.ms, method.error.message, and more) so queries target real fields. - Ready-to-Use TraceQL Queries: Prebuilt queries for finding errors, filtering by component layer, detecting slow operations, and searching span inputs by content. - Debugging Workflows: Structured processes for investigating failed requests, performance regressions, and request flows, plus PromQL queries for spanmetrics dashboards. - Use Case: An API returns 500 on POST /appointments. Query { status = error && class.module = "appointment" }, inspect method.error.message and method.input.json, and identify the missing validation in the use case. ## Quick Start Ask the AI to find all error spans in the appointment module from Grafana Tempo and explain the root cause using the span attributes.

Frequently Asked Questions about trace-analysis

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

FAQPage Schema
How do I find errors in Grafana Tempo traces?

Use a TraceQL query filtering on error status, such as { status = error && class.module = "appointment" }. Then inspect the span attributes method.error.type, method.error.message, and method.error.stack to identify the failing class and root cause.

How do I find slow operations with TraceQL?

Query spans by duration, for example { method.duration.ms > 1000 } to find operations over one second. Narrow the scope by layer, such as { class.component = "repository" && method.duration.ms > 500 }, to isolate slow database calls.

What span attributes are available for trace filtering?

Spans include class.name, class.component (router, controller, service, repository, handler), class.module, method.name, method.duration.ms, method.input.json, method.output.json, and error fields like method.error.message. These come from the autoTrace instrumentation in the TypeScript daemon.

Why are traces missing in Grafana Tempo?

Missing traces usually mean the OTEL_COLLECTOR_TRACE_URL is not set in the config, startTelemetry() was not called at startup, or the class was not resolved through the DI container, which is required for autoTrace instrumentation to wrap its methods.

When should I not use trace analysis for debugging?

Avoid trace analysis for local development debugging, where console logs or a debugger are faster, and for frontend-only issues. Database performance problems are better investigated through Grafana dashboards rather than individual span inspection.