TraciumClient

The main client class for interacting with the Tracium API.

Rule of thumb

Prefer tracium.trace() for most apps. It initializes the SDK and enables auto-instrumentation in one call. Use tracium.init() only when you need advanced configuration, then call client.trace().

tracium.init()

Initialize the Tracium SDK with your configuration.

import tracium

client = tracium.init(
    api_key=None,                 # Or use TRACIUM_API_KEY
    base_url=None,                # Custom API endpoint
    config=None,                  # TraciumClientConfig for advanced settings
    default_agent_name="app",     # Default agent name for auto-traces
    default_model_id=None,        # Default model ID
    default_version=None,         # Your application version (not SDK version)
    default_tags=None,            # Default tags for all traces
    default_metadata=None,        # Default metadata
    auto_instrument_langchain=True,
    auto_instrument_langgraph=True,
    auto_instrument_llm_clients=True,
    capture_media=False,          # Capture audio/image outputs (base64)
)

tracium.trace()

One-line setup with automatic tracing enabled. This is the recommended approach for most use cases.

import tracium

# Initialize and enable auto-instrumentation in one call
client = tracium.trace(
    api_key=None,
    # ... same kwargs as init()
)

import tracium

# Example: opt-in to capturing audio/image media
client = tracium.trace(capture_media=True)

TraciumClient Methods

agent_trace()

Create a trace context manager for an agent workflow.

client.agent_trace(
    agent_name,               # Required: Name of your agent
    model_id=None,            # Model being used
    metadata=None,            # Custom metadata
    tags=None,                # Tags for filtering
    trace_id=None,            # Custom trace ID
    workspace_id=None,        # Workspace identifier
    version=None,             # Application version
    lazy_start=False,         # Defer trace creation until first span
) -> AgentTraceManager

# Usage
with client.agent_trace(agent_name="my-agent") as trace:
    # Create spans within this trace
    pass

trace()

Enable automatic tracing for all supported libraries.

client.trace() -> TraciumClient

# Usage
client = tracium.init(api_key="...")
client.trace()  # Enable auto-instrumentation

get_queue_stats()

Get statistics about the background sender queue.

client.get_queue_stats() -> dict

# Returns:
{
    "queue_size": int,           # Current events in queue
    "max_queue_size": int,       # Maximum capacity
    "capacity_percent": float,   # Queue fullness percentage
    "is_healthy": bool,          # Queue health status
    "total_enqueued": int,       # Total events added
    "total_sent": int,           # Successfully sent
    "total_failed": int,         # Failed to send
    "total_dropped": int,        # Dropped due to full queue
    "success_rate": float,       # Percentage sent successfully
    "drop_rate": float,          # Percentage dropped
    "blocking_enabled": bool,    # If blocking mode is on
}

flush()

Wait for all pending async requests to be sent.

client.flush(
    timeout=None  # Max wait time (default: 5.0)
) -> None

# Call before application exit
client.flush()

close()

Close the client and shutdown background sender.

client.close() -> None

# Or use as context manager
with tracium.TraciumClient(api_key="...") as client:
    # Use client
    pass  # Automatically closed

AgentTraceHandle

The handle returned by agent_trace() context manager.

Properties

trace.id -> str           # Trace ID
trace.agent_name -> str   # Agent name
trace.tags -> list[str]   # Current tags
trace.summary -> dict     # Trace summary
trace.start_payload -> dict

Methods

# Create a span within this trace
trace.span(
    span_type,
    name=None,
    input=None,
    metadata=None,
    tags=None,
    parent_span_id=None,
    span_id=None,
    model_id=None,
    # ... additional options
) -> AgentSpanContext

# Record a complete span in one call
trace.record_span(
    span_type,
    name=None,
    input=None,
    output=None,
    status=None,
    error=None,
    latency_ms=None,
    # ... additional options
) -> dict

# Set trace summary
trace.set_summary(summary) -> None

# Add tags
trace.add_tags(tags) -> None

# Mark trace as failed
trace.mark_failed(error, metadata=None) -> None

# Finish trace manually (usually automatic)
trace.finish(
    summary=None,
    metadata=None,
    tags=None,
) -> dict

# Mark as failed and finish
trace.fail(error, metadata=None) -> dict

AgentSpanHandle

The handle returned by trace.span() context manager.

Properties

span.id -> str             # Span ID
span.trace_id -> str       # Parent trace ID
span.parent_span_id -> str | None
span.payload -> dict       # Last recorded payload

Methods

# Record input data
span.record_input(input_data) -> None

# Record output data
span.record_output(output_data) -> None

# Set token usage
span.set_token_usage(
    input_tokens=None,
    output_tokens=None,
    cached_input_tokens=None,
) -> None

# Add tags
span.add_tags(tags) -> None

# Set status
span.set_status(status) -> None

# Mark as failed
span.mark_failed(error, metadata=None) -> None

Module-Level Functions

import tracium

# Get the globally initialized client
client = tracium.get_client()

# Get queue statistics from global client
stats = tracium.get_queue_stats()

# Start a trace using global defaults
with tracium.start_trace(
    agent_name="my-agent",
    model_id=None,
    version=None,
    metadata=None,
    tags=None,
    trace_id=None,
):
    pass

# Get current active trace (if any)
trace = tracium.current_trace()

# Create span within current trace
with tracium.span(
    span_type="tool",
    name=None,
    # ... span options
):
    pass

← Auto-Instrumentation Decorators →