Configuration

This page documents every configuration option available in Traccia, including config file sections, environment variables, and default values.

The default endpoint is the Traccia platform (https://api.traccia.ai/v2/traces). Override it only when using a custom OTLP backend.

[tracing]

service_name is auto-detected when not set. Python falls back to the script name or working directory. Node.js also checks OTEL_SERVICE_NAME, SERVICE_NAME, and TRACCIA_SERVICE_NAME. Pass service_role programmatically: init(service_role="orchestrator"). Use it for multi-agent host services so the host itself is not registered as an agent in the platform.

[exporters]

[instrumentation]

[metrics]

Metrics are emitted even when traces are heavily sampled, so you can keep sample_rate low for traces while keeping metrics_sample_rate at 1.0 for accurate cost and token usage.

[rate_limiting]

Note: Rate limiting is disabled by default (max_spans_per_second = None). Set a value to enable it.

[runtime]

TRACCIA_PROJECT is also supported as a legacy alias for project_id.

[logging]

[advanced]

Special Environment Variables

export AGENT_DASHBOARD_PRICING_JSON='{
  "gpt-4": {"input": 0.03, "output": 0.06},
  "gpt-3.5-turbo": {"input": 0.001, "output": 0.002}
}'

export AGENT_DASHBOARD_AGENT_CONFIG="/path/to/agent_config.json"

export OTEL_SERVICE_NAME="my-agent-service"

Example Configurations

[tracing]
use_otlp = false

[exporters]
enable_console = true

[logging]
debug = true
enable_span_logging = false

[tracing]
endpoint = "http://localhost:4318/v1/traces"
use_otlp = true
service_name = "my-agent"
sample_rate = 1.0

[instrumentation]
enable_patching = true
enable_token_counting = true
enable_costs = true

[tracing]
api_key = "tr_live_xxxxxxxxxxxx"
endpoint = "https://api.traccia.ai/v2/traces"
sample_rate = 0.1
service_name = "production-agent"

[rate_limiting]
max_spans_per_second = 100.0
max_queue_size = 5000

[runtime]
agent_id = "my-agent"
agent_name = "My Agent"
env = "production"
tenant_id = "acme-corp"
project_id = "customer-service"

[logging]
debug = false

from traccia import init, runtime_config

init(
    api_key="tr_live_xxxxxxxxxxxx",
    service_name="my-orchestrator-api",
    service_role="orchestrator",   # prevents this service being registered as an agent
    auto_start_trace=False,
)

with runtime_config.run_identity(agent_id="billing-agent", agent_name="Billing Agent", env="production"):
    # all traces/metrics in this block are attributed to billing-agent
    ...

Governance

Passed to init() / start_tracing(). See Python SDK API (Governance section).

compliance example: {"frameworks": ["eu_ai_act"], "risk_tier": "high"}. Human review is not an SDK option — use the Governance Hub.

Advanced — runtime policy URLs

Optional [governance] in traccia.toml. Not required for normal use — status and block URLs are derived from your tracing endpoint. See Governance guide.

[governance]
# Advanced only — omit for standard Traccia deployments
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