Documentation Index
Fetch the complete documentation index at: https://traceroot.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
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,
Integration.GOOGLE_GENAI,
],
)
The Observe Decorator
Wrap any function to create a span, works with sync functions, async functions, and generators.
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
| Parameter | Type | Default | Description |
|---|
name | str | function name | Span name |
type | SpanKind | str | "span" | Span kind: "llm", "agent", "tool", or "span" (accepts both SpanKind enum and string values) |
metadata | dict | None | Static metadata to attach |
tags | list[str] | None | Tags to attach |
capture_input | bool | True | Whether to auto-capture function arguments as input |
capture_output | bool | True | Whether to auto-capture the return value as output |
session_id | str | None | Session identifier to attach to the trace |
user_id | str | None | User identifier to attach to the trace |
Setting Trace Context
Use using_attributes to set user and session context for all spans created within a block:
from traceroot import using_attributes
with using_attributes(
user_id="user-123",
session_id="sess-456",
tags=["production", "v2"],
metadata={"feature": "chat"},
):
result = run_agent("What is the weather?")
Parameters
| Parameter | Type | Description |
|---|
user_id | str | User identifier |
session_id | str | Session / conversation ID |
tags | list[str] | Tags to attach to all spans |
metadata | dict | Arbitrary metadata |
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"],
metadata={"plan": "pro", "region": "us-east-1"},
)
update_current_span Parameters
| Parameter | Type | Description |
|---|
name | str | Update the span name |
input | Any | Input data |
output | Any | Output data |
metadata | dict | Custom metadata key-value pairs |
model | str | LLM model name (e.g., "gpt-4o") |
model_parameters | dict | Model parameters (e.g., temperature, max_tokens) |
usage | dict | Token usage (e.g., {"input_tokens": 100, "output_tokens": 50}) |
prompt | Any | Prompt/messages sent to the LLM |
update_current_trace Parameters
| Parameter | Type | Description |
|---|
user_id | str | User who initiated the trace |
session_id | str | Session identifier for grouping traces |
metadata | dict | Trace-level metadata |
tags | list[str] | Tags to categorize the trace |
Environment Variables
All parameters can be set via environment variables:
| Variable | Default | Description |
|---|
TRACEROOT_API_KEY | (required) | API key |
TRACEROOT_HOST_URL | https://app.traceroot.ai | API endpoint |
TRACEROOT_ENABLED | true | Enable/disable tracing |
TRACEROOT_ENVIRONMENT | — | Deployment environment tag (e.g. production, staging) |
TRACEROOT_FLUSH_INTERVAL | 5.0 | Flush interval in seconds |
TRACEROOT_FLUSH_AT | 100 | Batch size before flush |
TRACEROOT_TIMEOUT | 30.0 | HTTP timeout in seconds |
TRACEROOT_GIT_REPO | auto-detected | Git repository (owner/repo) |
TRACEROOT_GIT_REF | auto-detected | Git reference |
