Guide · Agent skill
How to use the Distributed Tracing agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The distributed-tracing skill gives an AI agent a practical playbook for following a single request as it moves between microservices, using Jaeger and Tempo. It is aimed at backend engineers, platform and SRE teams, and developers who want trace and log correlation explained. After this guide you will know how to install the skill, how to phrase requests so the agent uses it, and what to check before acting on its advice.
Distributed Tracingwshobson/agents · MIT Download the skill Quick start
- 1Download the ZIP. Get the distributed-tracing skill ZIP from the item page.
- 2Unzip into a skills folder. Extract it into ~/.claude/skills/ for personal use, or into the project's .claude/skills/ for one project.
- 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP if that option is available to you.
- 4Describe the problem. Ask about slow or failing requests across services, naming the services and symptoms.
- 5Review the output. Check any sampling rate, overhead figure or config change against your own system before applying it.
What does the distributed tracing skill make the agent do?
A trace records the journey of one request through your system. Each operation inside it is a span, and spans carry timing, tags and events. The skill teaches the agent these concepts and guides it on instrumentation, sampling, adding useful tags, correlating logs with trace IDs and troubleshooting missing traces.
The skill's own description says it is for implementing distributed tracing with Jaeger and Tempo to find performance bottlenecks. It also points to related skills for metrics, dashboards and latency SLOs. It gives guidance rather than deploying anything.
- Explains traces, spans, context, tags and logs
- Covers sampling, batch span processing and span events
- Shows how to put a trace ID into log lines
- Lists first checks when traces are missing or overhead is high
How do you install the distributed tracing skill?
Download the skill ZIP from the item page. Then choose one of two locations. For a personal install available in all your projects, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the project's .claude/skills/ folder.
You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills, if your plan and app version offer that option.
- Personal: unzip into ~/.claude/skills/
- Project: unzip into .claude/skills/ inside the project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What files are in the skill?
The package contains two files. SKILL.md holds the main guidance: purpose, when to use it, best practices, a correlated logging example and a troubleshooting checklist. references/details.md holds longer patterns and worked examples, such as a trace structure diagram and a Jaeger Kubernetes deployment example.
The agent reads references/details.md when the main guidance is not enough, so you do not need to open it yourself to use the skill.
- SKILL.md: main playbook
- references/details.md: detailed patterns and worked examples
How do you trigger the skill with a natural request?
You do not need a special command. Describe the problem in plain terms that involve requests, services or latency, and the agent can match the skill's description. Include the symptom, the services involved and what you have already checked.
Good requests name the situation. Vague requests like 'make it faster' are less likely to pull in the right guidance.
- 'Requests from checkout to payment are taking over two seconds. Help me trace where the time goes.'
- 'Some errors start in the order service but I can't tell which upstream call causes them. How should I trace this?'
- 'Our Jaeger traces stopped showing up after the last deploy. What should I check?'
- 'Add trace IDs to our log lines so we can match logs to a request in Tempo.'
What do the examples look like in practice?
The correlated logs example in SKILL.md gets the current span from OpenTelemetry, reads its trace ID, and adds it to a log record as a 32-character hex string. This lets you find the logs for one request from its trace.
The troubleshooting section lists checks for two common problems. If no traces appear, check the collector endpoint, network connectivity, sampling configuration and application logs. If overhead is high, reduce the sampling rate, use the batch span processor and check exporter configuration.
import logging
from opentelemetry import trace
logger = logging.getLogger(__name__)
def process_request():
span = trace.get_current_span()
trace_id = span.get_span_context().trace_id
logger.info(
"Processing request",
extra={"trace_id": format(trace_id, '032x')}
)What does the skill need, and is it safe to run?
The skill lists no requirements. It does not run scripts and does not use the network. Its files are Markdown guidance, so installing it does not deploy Jaeger, Tempo or any service.
Treat the advice as a starting point. The sampling rate (1-10% in production) and the overhead target (under 1% CPU) are general guidance. Check them against your own traffic and capacity, and review any production change before you make it.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
- Review sampling and overhead targets against your own system before changing production
What people use it for
- Finding which service in a checkout request adds the most latency
- Working out why errors in one service trace back to an upstream call
- Adding trace IDs to logs so one request's logs can be found in Jaeger or Tempo
- Diagnosing missing traces after a deployment by checking collector endpoints and sampling
- Planning instrumentation standards such as consistent span names and useful tags
Frequently asked questions
How do I install the distributed tracing agent skill?
Download the ZIP from the item page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
Is the distributed-tracing skill free?
The skill is licensed under MIT. The source listing does not state any price, so check the item page for current terms.
What do I need to use this skill?
The skill lists no requirements. It does not run scripts or use the network, so it only provides guidance to the agent. You still need your own tracing system, such as Jaeger or Tempo, to actually collect traces.
Does the skill set up Jaeger or Tempo for me?
No. It gives guidance rather than deploying anything. The reference file includes example Jaeger Kubernetes deployment commands for you to review and adapt.
Why are my traces not showing up in Jaeger?
The skill's troubleshooting checklist suggests checking the collector endpoint, network connectivity, the sampling configuration and application logs. Work through these in order to find where traces are lost.
How does this compare with ordinary profiling or logs?
For a single-process application with no service boundaries, ordinary profiling or logs are usually simpler. Distributed tracing is most useful when a request crosses several services and you need to see where time is spent between them.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you are a backend engineer, or a platform or SRE team, debugging slow or failing requests across several microservices with Jaeger or Tempo. Pick something else if you have a single-process app, which profiling or logs can handle more simply, or if you need a finished tracing system deployed for you. Check every sampling and overhead recommendation against your own system before changing production.
Download the skill