Traccia AI工作流平台

API key — required for the Traccia platform, not needed for local OTLP backends

api_key = ""

Install in editable mode with dev dependencies

pip install -e ".[dev]"

Installation

pip install traccia

Development Setup

```bash

🚀 Quick Start

Basic Usage

```python from traccia import init, observe

🎯 Usage Guide

Basic usage

@observe() def process_data(data): return transform(data)

• Sample Rate: 1.0

Sample 10% of traces

init(sample_rate=0.1)

OR set environment variable: TRACCIA_OPENAI_AGENTS=false

OR set environment variable: TRACCIA_CREWAI=false

📖 Configuration

Configuration Precedence

Traccia merges configuration from multiple sources with the following priority (highest to lowest):

1. Explicit parameters — init(endpoint="...", agent_id="...") or start_tracing(...)
2. Environment variables — TRACCIA_ENDPOINT, TRACCIA_AGENT_ID, etc.
3. Config file — traccia.toml (current directory) or ~/.traccia/config.toml
4. Defaults — Built-in SDK defaults

Example: If you set TRACCIA_ENDPOINT in your environment and pass endpoint=... to init(), the explicit parameter wins.

---

Configuration File

Create a traccia.toml file in your project root:

traccia config init

This creates a template config file:

```toml [tracing]

service_name = "my-app" # Optional service name

service_role has no env var — pass via init(service_role="orchestrator")

[exporters]

Optional: limit spans per second

Optional runtime metadata (agent identity: prefer init(agent_id=..., agent_name=..., env=...) or TRACCIA_* env)

env = "" # e.g. production, staging, dev

[logging] debug = false # Enable debug logging enable_span_logging = false # Enable span-level logging

[advanced]

Environment Variables

All config parameters can be set via environment variables with the TRACCIA_ prefix:

Tracing: TRACCIA_API_KEY, TRACCIA_ENDPOINT, TRACCIA_SAMPLE_RATE, TRACCIA_AUTO_START_TRACE, TRACCIA_AUTO_TRACE_NAME, TRACCIA_USE_OTLP, TRACCIA_SERVICE_NAME

Exporters: TRACCIA_ENABLE_CONSOLE, TRACCIA_ENABLE_FILE, TRACCIA_FILE_PATH, TRACCIA_RESET_TRACE_FILE

Instrumentation: TRACCIA_ENABLE_PATCHING, TRACCIA_ENABLE_TOKEN_COUNTING, TRACCIA_ENABLE_COSTS, TRACCIA_AUTO_INSTRUMENT_TOOLS, TRACCIA_MAX_TOOL_SPANS, TRACCIA_MAX_SPAN_DEPTH, TRACCIA_OPENAI_AGENTS, TRACCIA_CREWAI, TRACCIA_GUARDRAIL_HEURISTICS

Rate Limiting: TRACCIA_MAX_SPANS_PER_SECOND, TRACCIA_MAX_QUEUE_SIZE, TRACCIA_MAX_BLOCK_MS, TRACCIA_MAX_EXPORT_BATCH_SIZE, TRACCIA_SCHEDULE_DELAY_MILLIS

Runtime: TRACCIA_SESSION_ID, TRACCIA_USER_ID, TRACCIA_TENANT_ID, TRACCIA_PROJECT_ID, TRACCIA_AGENT_ID, TRACCIA_AGENT_NAME, TRACCIA_ENV

Legacy alias: TRACCIA_PROJECT (maps to project_id)

Logging: TRACCIA_DEBUG, TRACCIA_ENABLE_SPAN_LOGGING

Advanced: TRACCIA_ATTR_TRUNCATION_LIMIT

Programmatic Configuration

```python from traccia import init

Override config programmatically (including agent identity for single-agent services)

init( endpoint="http://tempo:4318/v1/traces", sample_rate=0.5, enable_costs=True, max_spans_per_second=100.0, agent_id="my-agent", agent_name="My Agent", env="production", ) ```

`traccia config init`

Create a new traccia.toml configuration file:

traccia config init
traccia config init --force  # Overwrite existing

🩺 Running Traccia configuration diagnostics...

#

✅ Found config file: ./traccia.toml

✅ Configuration is valid

#

📊 Configuration summary:

• API Key: ❌ Not set (optional)

Environment variable (persistent across restarts)

export TRACCIA_PRICING_OVERRIDE_JSON='{"gpt-4o": {"prompt": 0.005, "completion": 0.015}}' ```

Deprecation notice: AGENT_DASHBOARD_PRICING_JSON is accepted as a back-compat alias for TRACCIA_PRICING_OVERRIDE_JSON but will be removed in a future minor version. Rename the variable in your environment.

Platform overrides (org-level): Org admins can set pricing overrides in Settings → Pricing on the Traccia platform. These apply to the platform-recomputed cost (platform_cost_usd) for all agents in the org. They do not change llm.cost.usd on existing spans retroactively unless you explicitly enable the "Also recompute past traces" option in the save dialog.

---

Or via config

init(debug=True)

Or via env var

Configuration

load_config(config_file=None, overrides=None) -> TracciaConfig

Load and validate configuration.

Parameters: - config_file (str, optional): Path to config file - overrides (dict, optional): Override values

Returns: Validated TracciaConfig instance

Raises: ConfigError if invalid

validate_config(config_file=None, overrides=None) -> tuple[bool, str, TracciaConfig | None]

Validate configuration without loading.

Returns: Tuple of (is_valid, message, config_or_none)

---

Create virtual environment

python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

OpenAI Agents SDK

Traccia automatically detects and instruments the OpenAI Agents SDK when installed. No extra code needed:

from traccia import init
from agents import Agent, Runner

init()  # Automatically enables Agents SDK tracing

agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant"
)
result = Runner.run_sync(agent, "Write a haiku about recursion")

Configuration: Auto-enabled by default when openai-agents is installed. To disable:

```python init(openai_agents=False) # Explicit parameter

Endpoint URL for OTLP trace ingestion (default: Traccia platform)

For local OTLP backends use e.g. endpoint = "http://localhost:4318/v1/traces"

endpoint = "https://api.traccia.ai/v2/traces"

sample_rate = 1.0 # 0.0 to 1.0 auto_start_trace = true # Auto-start root trace on init auto_trace_name = "root" # Name for auto-started trace use_otlp = true # Use OTLP exporter

metrics_endpoint = "" # Defaults to {traces_base}/v2/metrics

metrics_sample_rate = 1.0 # Metrics sampling rate (1.0 = 100%)

[runtime]

Default endpoint

If you do not set endpoint (in config, environment, or when calling init() / start_tracing()), the SDK uses the Traccia platform by default (https://api.traccia.ai/v2/traces). You can override it to send traces to your own OTLP-compatible backend.

The default is defined in traccia.config: DEFAULT_OTLP_TRACE_ENDPOINT. The alias DEFAULT_ENDPOINT is kept for backward compatibility (same value).

🛠️ CLI Tools

Traccia includes a powerful CLI for configuration and diagnostics:

• Endpoint: https://api.traccia.ai/v2/traces

Remove local cache — reverts to the bundled snapshot shipped with the SDK

traccia pricing clear ```

---

📚 API Reference

Clone the repository (Python SDK)

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

Instrumentation vs Integrations

• traccia.instrumentation.*: Infrastructure and vendor instrumentation.
• HTTP client/server helpers (including FastAPI middleware).
• Vendor SDK hooks and monkey patching (e.g., OpenAI, Anthropic, Gemini, requests).
• Decorators and utilities used for auto-instrumenting arbitrary functions.

• traccia.integrations.*: AI/agent framework integrations.
• Adapters that plug into higher-level frameworks via their official extension points (e.g., LangChain callbacks).
• Work at the level of chains, tools, agents, and workflows rather than raw HTTP or SDK calls.

---

`@observe` vs `@govern`

@govern does two things:

1. Checks agent status before the function body (can warn or stop the next run for after-ingest policies).
2. Turns on a per-call check for this LLM or tool call (Spend Cap, Model Boundary, Loop Cap). You do not call check_policy() yourself when using an instrumented LLM client and @observe(as_type="tool").

Tracing-only or self-hosted users should use @observe.

from openai import OpenAI
from traccia import init, observe, govern, AgentBlockedError

init(api_key="...", endpoint="https://api.traccia.ai/v2/traces", agent_id="my-agent")
client = OpenAI()

@observe(name="lookup_order", as_type="tool")
def lookup_order(order_id: str) -> dict:
    return {"order_id": order_id, "status": "shipped"}

@govern(fail_open=False, name="run_agent")
def run_agent(prompt: str) -> str:
    lookup_order("ORD-1")
    resp = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
    )
    return resp.choices[0].message.content or ""

try:
    run_agent("hello")
except AgentBlockedError as exc:
    print(exc.reasons, exc.decision_id, exc.remaining_budget_usd)

Identity comes from init(agent_id=...) (or TRACCIA_AGENT_ID). Pass agent_id on @govern only to override in a multi-agent process. fail_open=True (default) lets the agent continue if Traccia is unreachable. On Block deny, @govern raises AgentBlockedError. Observe and Warn still let the call proceed and record a match. Refund Guard and Purchase Guard can hold a middle amount: @govern raises ApprovalPending, which is not AgentBlockedError. Catch it, do not run the tool, and do not retry the check. pending_tool_result() is a normal tool result when a framework retries raised errors.

For a custom tool that is not wrapped with @observe(as_type="tool"), call check_policy(action={"type": "tool_call", "name": "refund"}, context={"input": {"amount": amount}}) yourself.

Policies in the app: Policies. SDK guide: Governance in the SDK.

Advanced (optional): override endpoints or cache TTL in traccia.toml:

[governance]
status_check_endpoint = "https://custom.example/agents/{agent_id}/status"
post_block_endpoint = "https://custom.example/agents/{agent_id}/blocks"
status_cache_ttl_seconds = 120

Or pass status_check_endpoint, post_block_endpoint, or status_cache_ttl_seconds to init().

🔧 Troubleshooting