Skip to main content
The TraceRoot Python SDK provides automatic and manual instrumentation for AI agents using OpenTelemetry.

​
Instrumentation

import traceroot
from traceroot import Integration

traceroot.initialize(
    integrations=[
        Integration.OPENAI,
        Integration.ANTHROPIC,
        Integration.LANGCHAIN,
    ],
)

​
The Observe Decorator

Wrap any function to create a span, works with both sync and async functions. 
from traceroot import observe

@observe(name="my_function", type="tool")
def my_function(query: str) -> str:
    return do_work(query)

@observe(name="async_agent", type="agent")
async def async_agent(query: str) -> str:
    return await process(query)

​
Parameters

ParameterTypeDefaultDescription
namestrfunction nameSpan name
typeSpanKind | str"span"Span kind: "llm", "agent", "tool", or "span" (accepts both SpanKind enum and string values)
metadatadictNoneStatic metadata to attach
tagslist[str]NoneTags to attach

​
Setting Trace Context

Use using_attributes to set user and session context: 
from traceroot import using_attributes

with using_attributes(user_id="user-123", session_id="sess-456"):
    result = run_agent("What is the weather?")
All traces created within the block inherit the user_id and session_id.

​
Updating Spans and Traces

Update the current span or trace programmatically: 
from traceroot import update_current_span, update_current_trace

# Update the current span
update_current_span(
    name="custom_name",
    input={"query": "hello"},
    output={"response": "world"},
    metadata={"custom_key": "custom_value"},
    # LLM-specific attributes (useful for custom/unsupported providers)
    model="gpt-4o",
    model_parameters={"temperature": 0.7, "max_tokens": 1024},
    usage={"input_tokens": 100, "output_tokens": 50},
    prompt=[{"role": "user", "content": "hello"}],
)

# Update the current trace
update_current_trace(
    user_id="user-123",
    session_id="sess-456",
    tags=["production", "v2"],
)

​
update_current_span Parameters

ParameterTypeDescription
namestrUpdate the span name
inputAnyInput data
outputAnyOutput data
metadatadictCustom metadata key-value pairs
modelstrLLM model name (e.g., "gpt-4o")
model_parametersdictModel parameters (e.g., temperature, max_tokens)
usagedictToken usage (e.g., {"input_tokens": 100, "output_tokens": 50})
promptAnyPrompt/messages sent to the LLM

​
update_current_trace Parameters

ParameterTypeDescription
user_idstrUser who initiated the trace
session_idstrSession identifier for grouping traces
metadatadictTrace-level metadata
tagslist[str]Tags to categorize the trace

​
Environment Variables

All parameters can be set via environment variables:
VariableDefaultDescription
TRACEROOT_API_KEY(required)API key
TRACEROOT_HOST_URLhttps://app.traceroot.aiAPI endpoint
TRACEROOT_ENABLEDtrueEnable/disable tracing
TRACEROOT_FLUSH_INTERVAL5.0Flush interval in seconds
TRACEROOT_FLUSH_AT100Batch size before flush
TRACEROOT_TIMEOUT30.0HTTP timeout in seconds
TRACEROOT_GIT_REPOauto-detectedGit repository (owner/repo)
TRACEROOT_GIT_REFauto-detectedGit reference