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

Installation

Install the core SDK via pip:

Optional Extras

Some integrations have additional dependencies and are available as extras:
Framework packages (such as openai, anthropic, or langchain-core) are installed separately alongside your application.

Initialization

Call traceroot.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.
Repeat calls are ignored: Calling traceroot.initialize() more than once logs a warning and returns the existing client instance without applying new parameters or integrations. Pass every setting you need on the first call; the SDK cannot be reconfigured once initialized.

initialize() Parameters

Supported Integrations

The Integration 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

Use using_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

The traceroot package exports client management and OpenTelemetry context utilities:

Exported Utilities

Offline Evaluations

traceroot includes a complete offline evaluation framework exported directly from the top-level traceroot 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
Evaluation symbols are loaded lazily on demand to keep imports lightweight.

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 except integrations can be configured via environment variables: