TraciumClient

import tracium

client = tracium.init(
    api_key: str | None = None,              # API key (or TRACIUM_API_KEY env var)
    base_url: str | None = None,             # Custom API endpoint
    config: TraciumClientConfig | None = None,
    default_agent_name: str = "app",         # Default agent name for auto-traces
    default_model_id: str | None = None,     # Default model ID
    default_version: str | None = None,      # Your application version
    default_tags: list[str] | None = None,   # Default tags for all traces
    default_metadata: dict | None = None,    # Default metadata
    auto_instrument_langchain: bool = True,
    auto_instrument_langgraph: bool = True,
    auto_instrument_llm_clients: bool = True,
) -> TraciumClient

import tracium

# Initialize and enable auto-instrumentation in one call
client = tracium.trace(
    api_key: str | None = None,
    **kwargs  # Same parameters as init()
) -> TraciumClient

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

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

client.trace() -> TraciumClient

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

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
}

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

# Call before application exit
client.flush()

client.close() -> None

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

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

# Create a span within this trace
trace.span(
    span_type: str,
    name: str | None = None,
    input: Any = None,
    metadata: dict | None = None,
    tags: list[str] | None = None,
    parent_span_id: str | None = None,
    span_id: str | None = None,
    model_id: str | None = None,
    # ... additional options
) -> AgentSpanContext

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

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

# Add tags
trace.add_tags(tags: list[str]) -> None

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

# Finish trace manually (usually automatic)
trace.finish(
    summary: dict | None = None,
    metadata: dict | None = None,
    tags: list[str] | None = None,
) -> dict

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

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

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

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

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

# Add tags
span.add_tags(tags: list[str]) -> None

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

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

import tracium

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

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

# Start a trace using global defaults
with tracium.start_trace(
    agent_name: str | None = None,
    model_id: str | None = None,
    version: str | None = None,
    metadata: dict | None = None,
    tags: list[str] | None = None,
    trace_id: str | None = None,
) -> AgentTraceManager:
    pass

# Get current active trace (if any)
trace = tracium.current_trace() -> AgentTraceHandle | None

# Create span within current trace
with tracium.span(
    span_type: str,
    name: str | None = None,
    # ... span options
) -> AgentSpanContext:
    pass