Exporters

Traccia supports multiple exporters for sending traces to different backends. You can use OTLP for production observability platforms, console for local debugging, or file for offline analysis.

OTLP Exporter (Default)

The OpenTelemetry Protocol (OTLP) exporter is the default and recommended option for production. When no endpoint is set, the SDK sends traces to the Traccia platform (https://api.traccia.ai/v2/traces). OTLP is also compatible with Jaeger, Grafana Tempo, Zipkin, Honeycomb, Datadog, and other backends.

Configuration

from traccia import init

# OTLP is enabled by default (use_otlp=True)
# Default endpoint is the Traccia platform - just set api_key:
init(api_key="tr_live_xxxxxxxxxxxx")

# Local Jaeger
init(endpoint="http://localhost:4318/v1/traces")

# Local Grafana Tempo
init(endpoint="http://localhost:4318/v1/traces")

# Traccia Platform (explicit endpoint - optional, this is the default)
init(
    api_key="tr_live_xxxxxxxxxxxx",
    endpoint="https://api.traccia.ai/v2/traces"
)

# Grafana Cloud
init(
    endpoint="https://otlp-gateway-prod.grafana.net/otlp/v1/traces",
    api_key="your-grafana-api-key"
)

Via Configuration File

[tracing]
endpoint = "http://localhost:4318/v1/traces"
use_otlp = true  # Default

# Optional authentication
api_key = "your-api-key"

Features

OTLP Resource Attributes

OTLP exports attach resource attributes to every span batch. The SDK resolves service.name from config, OTEL_SERVICE_NAME, TRACCIA_SERVICE_NAME, or the current working directory / script name. Identity fields from runtime config are included when set.

{
  "service.name": "my-agent-app",
  "tenant.id": "acme-corp",
  "agent.id": "research-assistant",
  "agent.name": "Research Assistant",
  "session.id": "session-abc123",
  "user.id": "user-xyz789",
  "env": "production",
  "traccia.service_role": "orchestrator",
  "trace.debug": false
}

Console Exporter

The console exporter prints traces to stdout (terminal). Perfect for local development and debugging when you want to see traces without setting up an external backend.

Configuration

from traccia import init

# Enable console exporter
init(enable_console_exporter=True)

# Or with debug logging
init(
    enable_console_exporter=True,
    debug=True
)

Via Configuration File

[tracing]
use_otlp = false  # Disable OTLP

[exporters]
enable_console = true

Example Output

{
  "name": "my_agent",
  "context": {
    "trace_id": "0x1234567890abcdef",
    "span_id": "0xabcdef123456",
    "trace_state": "[]"
  },
  "kind": "SpanKind.INTERNAL",
  "parent_id": null,
  "start_time": "2024-01-15T10:30:00.000000Z",
  "end_time": "2024-01-15T10:30:02.500000Z",
  "status": {
    "status_code": "OK"
  },
  "attributes": {
    "query": "What is AI?",
    "llm.model": "gpt-4",
    "llm.usage.prompt_tokens": 45,
    "llm.usage.completion_tokens": 405,
    "llm.usage.total_tokens": 450,
    "llm.cost.usd": 0.0135
  }
}

Use Cases

• Local development without external dependencies
• Debugging instrumentation issues
• CI/CD pipeline testing
• Quick verification that tracing is working

File Exporter

The file exporter writes traces to a JSONL (JSON Lines) file on disk. Each span is written as a separate JSON object on its own line, making it easy to process with standard tools like jq, grep, or scripts.

Configuration

from traccia import init

# Enable file exporter (often alongside OTLP for local capture)
init(
    enable_file_exporter=True,
    file_exporter_path="traces.jsonl"
)

# Reset file on each run
init(
    enable_file_exporter=True,
    file_exporter_path="traces.jsonl",
    reset_trace_file=True
)

Via Configuration File

[tracing]
use_otlp = false  # Disable OTLP

[exporters]
enable_file = true
file_exporter_path = "traces.jsonl"
reset_trace_file = false  # Append to existing file

Processing Traces

# View traces with jq
cat traces.jsonl | jq

# Filter for errors
cat traces.jsonl | jq 'select(.status.status_code == "ERROR")'

# Count spans by type
cat traces.jsonl | jq -r '.attributes."span.type"' | sort | uniq -c

# Calculate total cost
cat traces.jsonl | jq -r '.attributes."llm.cost.usd" // 0' | awk '{sum+=$1} END {print sum}'

Use Cases

• Offline analysis and reporting
• Audit trails and compliance
• Custom processing with scripts
• Sharing traces without external infrastructure
• Testing and integration tests

Choosing an Exporter

Batching and Performance

All exporters use batching to improve performance. You can configure batch size and delay:

from traccia import start_tracing

start_tracing(
    endpoint="http://localhost:4318/v1/traces",
    
    # Batch configuration
    max_export_batch_size=512,     # Max spans per batch
    schedule_delay_millis=5000,    # Batch every 5 seconds
    max_queue_size=5000,           # Max queued spans
)