Traccia ships two SDKs with the same tracing model: a Python SDK on PyPI and a TypeScript SDK on npm (runs on Node.js 16+). Use whichever matches your agent stack — APIs and span attributes are aligned across both.

Basic Installation

Python

Install from PyPI using pip or poetry:

bash

pip install traccia

TypeScript

Install from npm. The package includes TypeScript definitions and also works from plain JavaScript on Node.js:

bash

npm install @traccia/sdk

Requirements

Python SDK

Python 3.9 or higher

Tested on 3.9, 3.10, 3.11, and 3.12

Package manager

pip, poetry, or any PyPI-compatible tool

TypeScript SDK

Node.js 16 or higher

LTS releases recommended for production

Package manager

npm, yarn, or pnpm

Core Dependencies

Each SDK installs its own OpenTelemetry and helper libraries automatically:

Python

tiktoken ≥ 0.7.0— Token counting for LLM calls

opentelemetry-api ≥ 1.20.0— OpenTelemetry core API

opentelemetry-sdk ≥ 1.20.0— OpenTelemetry SDK implementation

opentelemetry-exporter-otlp-proto-http ≥ 1.20.0— OTLP HTTP exporter

pydantic ≥ 2.0.0— Configuration validation

TypeScript

@opentelemetry/api— OpenTelemetry core API

@opentelemetry/sdk-trace-base— Trace SDK

@opentelemetry/exporter-trace-otlp-proto— OTLP exporter

zod— Configuration validation

No heavy dependencies

Neither SDK requires OpenAI, Anthropic, or other LLM client libraries. Auto-instrumentation activates when those packages are already present in your project.

Verify Installation

Confirm the SDK and CLI are available:

bash

# Check version
python -c "import traccia; print(traccia.__version__)"

# Verify CLI is available
traccia --help

Expected output (Python):

text

0.1.22

usage: traccia [-h] [--config CONFIG] {check,config,doctor,pricing} ...

Traccia SDK - Production-ready tracing for AI agents

Expected output (TypeScript):

text

0.1.4

Usage: traccia-ts [options] [command]

Traccia SDK CLI for TypeScript / Node.js

Development Installation

To contribute or install from source, clone the language-specific repository:

bash

git clone https://github.com/traccia-ai/traccia-py.git
cd traccia-py

pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Troubleshooting

Python

`ModuleNotFoundError: No module named 'traccia'`

Ensure Traccia is installed in the active virtual environment.

bash

which python
pip list | grep traccia

`command not found: traccia`

Add pip's script directory to your PATH, or invoke the module directly:

bash

python -m traccia --help
export PATH="$PATH:~/.local/bin"

TypeScript

`Cannot find module '@traccia/sdk'`

Install the package in your project directory and restart your dev server or REPL.

bash

npm install @traccia/sdk
node -e "require('@traccia/sdk')"

`command not found: traccia-ts`

Run the CLI through npx or add node_modules/.bin to your PATH:

bash

npx traccia-ts --help
npx traccia-ts doctor

Docker Installation

Add Traccia to your dependency manifest, then install it in the image build step:

text

openai>=1.0.0
anthropic>=0.5.0
traccia>=0.1.22

Example Dockerfile:

Dockerfile

dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "main.py"]

Next Steps

SDK Quickstart

Get started with Traccia in under 5 minutes

Configuration

Learn about traccia.toml and environment variables

CLI Commands

traccia and traccia-ts config, doctor, and check commands