Installation
Install the core SDK viapip:
Optional Extras
Some integrations have additional dependencies and are available as extras:openai, anthropic, or langchain-core) are installed separately alongside your application.
Initialization
Calltraceroot.initialize() once at application startup to configure the SDK and enable auto-instrumentation for supported frameworks:
Auto-initialization: The
@observe decorator works without calling initialize(). If no client exists, @observe calls get_client(), which automatically initializes the SDK from environment variables (such as TRACEROOT_API_KEY). However, auto-initialization will not instrument any frameworks. To auto-instrument libraries, explicit initialize(integrations=[...]) is required.initialize() Parameters
Supported Integrations
TheIntegration enum (from traceroot import Integration) provides auto-instrumentation for 17 AI frameworks and model providers.
traceroot checks whether the required package is installed before instrumenting. If a package is not installed, the integration is skipped with a warning rather than raising an error.
The Observe Decorator
Wrap any function to create an OpenTelemetry span. Supports synchronous functions, asynchronous functions, and generators.Parameters
See Data Capture and Privacy for examples that keep sensitive function inputs and outputs off spans.
Setting Trace Context
Useusing_attributes to set user and session context for all spans created within a block. This is re-exported from OpenInference for convenience:
Parameters
Updating Spans and Traces
Update the active span or trace programmatically from within any traced function:Both
update_current_span and update_current_trace accept keyword-only arguments. Calling them with positional arguments will raise a TypeError.update_current_span Parameters
update_current_trace Parameters
SDK Utilities and Context
Thetraceroot package exports client management and OpenTelemetry context utilities:
Exported Utilities
Offline Evaluations
traceroot includes a complete offline evaluation framework exported directly from the top-leveltraceroot module:
- Datasets & Cases:
Dataset,DatasetSnapshot,EvalCase,pull_dataset,pull_dataset_version - Execution:
evaluate,evaluate_async,Evaluation,EvalRunResult,EvalItemResult,RunDatasetRef - Scorers & Metrics:
Scorer,ScorerContext,scorer,Score,ScoreSummary,llm_judge,DeferredScore - Exceptions:
DatasetConflictError,DatasetPublishAborted,EvalCompletionError
Evaluations Overview
Learn how offline evaluations work in traceroot.
Running Evals
Run your AI system against datasets and score outputs with
evaluate().Environment Variables
All parameters exceptintegrations can be configured via environment variables: