Troubleshooting Guide

Both

Diagnose and fix common Traccia SDK issues.

This guide helps you diagnose and resolve common issues with the Traccia SDK, from installation problems to missing traces.

Quick Diagnostic Commands

Start with these CLI commands to quickly identify issues:

Step 1: Validate Configuration

bash
traccia doctor

Checks for config files, environment variables, validates settings, and reports issues.

Step 2: Test Connectivity

bash
traccia check

Tests connectivity to your configured OTLP endpoint.

Step 3: Enable Debug Logging

bash
export TRACCIA_DEBUG=true

Enables detailed logging of SDK operations for debugging.

Common Issues

No traces appearing in backend

Symptom:

SDK runs without errors, but no traces in Jaeger/Grafana/Platform

Diagnosis steps:

  1. Run traccia doctor to check config
  2. Verify backend is running: curl http://localhost:4318/health
  3. Check sample_rate (should be 1.0 for testing)
  4. Verify auto_start_trace is enabled (default: true)
  5. Test with console exporter to confirm spans are created

Solutions:

python
# Test with console output first
from traccia import init


init(
    enable_console_exporter=True,
    debug=True
)


# If traces appear in console but not backend:
# 1. Check endpoint URL is correct
# 2. Verify backend is accepting OTLP
# 3. Run: traccia check --endpoint http://localhost:4318/v1/traces

Connection failed or endpoint unreachable

Symptom:

Errors like "Connection refused", "Endpoint unreachable", or timeouts

Diagnosis steps:

  1. Check if backend is running: docker ps (for Jaeger/Tempo)
  2. Verify port is accessible: telnet localhost 4318
  3. Check endpoint URL format (e.g. /v1/traces for local OTLP, /v2/traces for Traccia platform HTTP)
  4. For gRPC clients, use https://api.traccia.ai:4317 with OTEL_EXPORTER_OTLP_PROTOCOL=grpc — do not append /v2/traces. See Platform OTLP Ingestion
  5. Test with traccia check: traccia check

Solutions:

bash
# Start Jaeger if not running
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest


# Verify it's running
curl http://localhost:4318/


# Configure Traccia
export TRACCIA_ENDPOINT="http://localhost:4318/v1/traces"
traccia check

Config file not found or ignored

Symptom:

SDK doesn't use your traccia.toml settings

Diagnosis steps:

  1. Check file exists: ls traccia.toml
  2. Verify it's in the current directory or ~/.traccia/
  3. Check TOML syntax: python -c "import toml; toml.load('traccia.toml')"
  4. Ensure you're calling init() without overriding all values

Solutions:

bash
# Create config file
traccia config init


# Validate syntax
traccia doctor


# Explicitly specify config file
export TRACCIA_CONFIG="/path/to/traccia.toml"
python your_app.py

Import errors or missing modules

Symptom:

ModuleNotFoundError for traccia or dependencies

Solutions:

bash
# Verify installation
pip list | grep traccia


# Reinstall
pip install --force-reinstall traccia


# Check Python version (requires 3.9+)
python --version


# Verify you're in the right environment
which python
pip show traccia

Auto-instrumentation not working

Symptom:

OpenAI/Anthropic calls not appearing in traces

Diagnosis:

python
# Check if patching is enabled
from traccia import init


init(debug=True)  # Should log "Patched OpenAI" messages

Solutions:

  1. Ensure enable_patching=True (default)
  2. Call init() BEFORE importing OpenAI/Anthropic
  3. Check library versions (OpenAI ≥1.0.0, Anthropic ≥0.18.0)
  4. If still not working, use @observe() decorator manually

High memory usage or OOM errors

Symptom:

Application memory grows over time or crashes with OOM

Common causes:

  • Queue buildup (spans not exporting fast enough)
  • Very high span creation rate
  • Large attributes or results captured
  • Backend unreachable (spans queuing indefinitely)

Solutions:

python
# Reduce queue size and add rate limiting
init(
    max_queue_size=1000,  # Lower from default 5000
    max_spans_per_second=50,  # Cap span rate
    max_block_ms=10,  # Drop spans quickly if queue full
)


# Skip large results
@observe(skip_result=True)
def process_large_data():
    return huge_dataframe


# Truncate attributes
init(attr_truncation_limit=500)  # Truncate at 500 chars

Step-by-Step Debugging Workflow

1

Verify SDK Installation

bash
python -c "import traccia; print(traccia.__version__)"
traccia --help

Should print version and show CLI help

2

Validate Configuration

bash
traccia doctor
traccia check

Fix any issues reported

3

Test with Console Exporter

python
# Switch to console temporarily
init(enable_console_exporter=True, debug=True)


# Run your agent
# You should see JSON output in terminal

Verifies instrumentation is working

4

Check Backend Logs

bash
# Jaeger logs
docker logs jaeger


# Tempo logs
docker-compose logs tempo


# Look for OTLP ingestion errors or rejections

Backend may show why traces are rejected

5

Test with File Exporter

python
# Write to file for inspection
init(
    enable_file_exporter=True,
    file_exporter_path="debug_traces.jsonl"
)


# After running, inspect the file
cat debug_traces.jsonl | jq

Allows offline analysis of span structure

Performance Issues

Application is slower after adding Traccia

  • • Expected overhead: 50-200 microseconds per span
  • • If seeing ms+ overhead: Check for large arguments/results being captured
  • • Solution: Use skip_args and skip_result=True
  • • For high-frequency functions: Don't use @observe(), or sample aggressively

Token counting is slow

Token counting adds ~1-5ms per LLM call. If this is unacceptable:

python
init(enable_token_counting=False)

Getting More Help

Still stuck?

If you can't resolve your issue:
  1. Check the FAQ for common questions
  2. Review Error Reference for exception details
  3. Search GitHub issues
  4. Open a new issue with debug logs and configuration

Next Steps

CLI Commands

traccia doctor and check for diagnostics

Error Reference

Exception types and common errors

FAQ

Frequently asked questions

© 2026 Traccia.