This guide will help you install the Traccia SDK and start tracing your AI agents locally. You'll be able to export traces to any OpenTelemetry-compatible backend like Jaeger, Grafana Tempo, or Zipkin.

Platform by default

By default the SDK sends traces to the Traccia platform (api.traccia.ai). Set TRACCIA_API_KEY and call init() to use the platform. This quickstart uses local tracing (console or local OTLP) so you can try the SDK without an account. For the full platform, see Platform Getting Started. If you use the platform, see Agent identity to set agent and environment so traces are easy to find.

1Install the SDK

Install Traccia using pip:

bash

pip install traccia

2Initialize Traccia

Add initialization at the start of your application. For this quickstart we use the console exporter so you can see traces in your terminal without any extra setup:

main.py

python

from traccia import init

# Console output so you can see traces in the terminal
init(enable_console_exporter=True)

# Or: local Jaeger — init(endpoint="http://localhost:4318/v1/traces")
# Or: Traccia platform — set TRACCIA_API_KEY and init()

3Instrument Your Code

Use the @observe() decorator to trace any function. Use the same init() as in step 2 so traces show up in the console:

agent.py

python

from traccia import init, observe
from openai import OpenAI

# Same init as step 2 — console exporter for this quickstart
init(enable_console_exporter=True)

# Then create client
client = OpenAI()

@observe()
def research_agent(topic: str) -> str:
    """Research agent that gathers information on a topic."""
    
    # This LLM call is automatically traced
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": "You are a research assistant."},
            {"role": "user", "content": f"Research: {topic}"}
        ]
    )
    
    return response.choices[0].message.content

# Run your agent
result = research_agent("quantum computing")
print(result)

4View Your Traces

With the console exporter (from step 2), you'll see trace output in your terminal:

text

[Traccia] Trace: research_agent
├── Span: research_agent (duration: 2.4s)
│   ├── model: gpt-4
│   ├── tokens: 450 (prompt: 45, completion: 405)
│   ├── cost: $0.0135
│   └── status: success

What just happened?

Function tracing

The @observe() decorator automatically created a parent span for your agent.

Auto-instrumentation

The OpenAI call was automatically intercepted and traced as a child span.

Token tracking

Token counts and estimated costs were automatically attached to the OpenAI span.

Data Capture & PII Redaction

By default, Traccia captures prompts and LLM responses (truncated to 1000 characters) to help with debugging. This data stays in your configured backend. By default, Traccia redacts PII like emails and phone numbers before they leave your machine. If you have sensitive data concerns, you can disable specific processors or use skip_args on the @observe() decorator. See Security for configuration options.

Next Steps

Agent identity

Set agent and environment.

Configuration

traccia.toml and env vars.

Auto-Instrumentation

See all automatically traced libraries.

Jaeger Setup Guide

Detailed guide for local tracing.

SDK Quickstart