uselemma-tracing 3.0.0

OpenTelemetry-based tracing module for Lemma

uselemma-tracing

OpenTelemetry-based tracing for AI agents. Capture inputs, outputs, timing, token usage, and errors — then view everything in Lemma.

Installation

pip install uselemma-tracing

Quick Start

1. Register the tracer provider

Call register_otel once when your application starts. It reads LEMMA_API_KEY and LEMMA_PROJECT_ID from environment variables by default.

from uselemma_tracing import register_otel

register_otel()

You can also enable experiment mode globally for the process:

from uselemma_tracing import enable_experiment_mode

enable_experiment_mode()

2. Wrap your agent

wrap_agent creates a root OpenTelemetry span named ai.agent.run and records:

• ai.agent.name
• lemma.run_id
• lemma.is_experiment
• lemma.thread_id (when thread_id is passed at invocation time)

from uselemma_tracing import TraceContext, wrap_agent

def my_agent(ctx: TraceContext, user_message: str):
    result = do_work(user_message)
    ctx.on_complete(result)
    return result

wrapped = wrap_agent("my-agent", my_agent)
result, run_id, span = wrapped(
    "hello",
    {"thread_id": "thread_123", "is_experiment": False},
)

Export Behavior

• Spans are exported in run-specific batches keyed by lemma.run_id.
• A run batch is exported when its top-level ai.agent.run span ends.
• force_flush() exports remaining runs in separate batches per run.
• Spans with instrumentation_scope.name == "next.js" are excluded from export.

Environment Variables

Variable	Description
LEMMA_API_KEY	Your Lemma API key
LEMMA_PROJECT_ID	Your Lemma project ID

Both are required unless passed explicitly to register_otel().

Documentation

• Tracing Overview — concepts, API reference, and usage patterns

License

MIT