Setup

Each page in this section uses TypeScript and Python tabs for code and runtime-specific notes.

Environment variables

TypeScript
Python

export LEMMA_API_KEY="lma_..."
export LEMMA_PROJECT_ID="proj_..."

Variable	Required	Description
`LEMMA_API_KEY`	Yes	Your Lemma API key (`lma_...`). Find it in project settings.
`LEMMA_PROJECT_ID`	Yes	Your Lemma project ID (`proj_...`). Find it in project settings.
`LEMMA_BASE_URL`	No	Override the Lemma API base URL. Defaults to `https://api.uselemma.ai`. Used for self-hosted deployments only.

export LEMMA_API_KEY="lma_..."
export LEMMA_PROJECT_ID="proj_..."
# export LEMMA_BASE_URL="https://your-lemma-instance.example.com"  # optional

These map directly to the parameters of create_lemma_span_processor() and register_otel():

# Reads from env vars by default
register_otel()

# Or pass explicitly (overrides env vars)
register_otel(
    api_key="lma_...",
    project_id="proj_...",
    base_url="https://your-lemma-instance.example.com",  # optional
)

Install dependencies

TypeScript
Python

npm install @uselemma/tracing @opentelemetry/api

If you want automatic per-LLM-call spans, add provider instrumentation:

npm install @opentelemetry/instrumentation @arizeai/openinference-instrumentation-openai @arizeai/openinference-instrumentation-anthropic

pip install uselemma-tracing opentelemetry-api

For provider auto-instrumentation, install optional extras:

pip install "uselemma-tracing[openai]" openai
pip install "uselemma-tracing[anthropic]" anthropic

Register OpenTelemetry once at startup

TypeScript
Python

Call registerOTel() before code that creates spans.

// instrumentation.ts (Next.js)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { registerOTel } = await import("@uselemma/tracing");
    registerOTel();
  }
}

// tracer.ts (Node.js)
import { registerOTel } from "@uselemma/tracing";

registerOTel();

Call register_otel() before creating spans.

from uselemma_tracing import register_otel

register_otel()

If you already have a TracerProvider configured (for example, for Datadog or Jaeger), add Lemma as an additional processor instead of replacing the provider:

from opentelemetry import trace
from uselemma_tracing import create_lemma_span_processor

trace.get_tracer_provider().add_span_processor(create_lemma_span_processor())

See the Dual export guide for the full multi-destination setup.

Create a run

TypeScript
Python

A run is one top-level wrapAgent execution. Return the wrapped function result and runId so you can attach external signals later.

import { wrapAgent } from "@uselemma/tracing";

export const callAgent = async (userMessage: string) => {
  const wrapped = wrapAgent("my-agent", async ({ onComplete }, input) => {
    const response = await llmCall(input.userMessage);
    onComplete(response);
    return response;
  });

  const { result, runId } = await wrapped(
    { userMessage },
    { threadId: sessionThreadId } // optional; omit second arg if unused
  );
  return { result, runId };
};

See Wrapping your agent for threadId / isExperiment on the wrapped function.

A run is one top-level wrap_agent execution. Return run_id so you can correlate user feedback and other signals.

from uselemma_tracing import TraceContext, wrap_agent

async def run_agent(ctx: TraceContext, user_message: str):
    response = await llm_call(user_message)
    ctx.on_complete(response)
    return response

async def call_agent(user_message: str):
    wrapped = wrap_agent("my-agent", run_agent)
    result, run_id, _span = await wrapped(
        user_message,
        {"thread_id": session_thread_id},  # optional; omit second arg if unused
    )
    return result, run_id

See Wrapping your agent for thread_id / is_experiment on the wrapped function.

What is captured automatically vs manually

Understanding this boundary prevents the most common “data is missing” issues.

TypeScript
Python

Runs capture input, output, timing, and errors on the root span. Per-LLM-call detail requires OpenInference or manual llm.step spans. Tool arguments and results require manual tool.call spans. Business metadata is never automatic—set attributes on the run span.

Category	Automatic	Manual
Run input	`ai.agent.input` — set from the input argument at span start	—
Run output	`ai.agent.output` — set from return value or explicit `on_complete` call	—
Run timing	Span start/end timestamps	—
Run errors	Any unhandled exception, or `ctx.record_error(err)`	—
Per-LLM-call prompt and response	Requires `instrument_openai()` / `instrument_anthropic()`	Or write `llm.step` child spans manually
Per-LLM-call token counts, model name	Requires provider instrumentation	Or set `llm.tokens.`, `llm.model.` on `llm.step` span
Tool arguments and results	Not captured	Add a `tool.call` child span per tool execution
Business metadata (user ID, session, etc.)	Not captured	`ctx.span.set_attribute("lemma.user_id", ...)`

Optional: add OpenInference instrumentors

Use this when you want provider-generated LLM spans to appear as run children.

TypeScript
Python

import { registerOTel } from "@uselemma/tracing";
import { registerInstrumentations } from "@opentelemetry/instrumentation";
import { OpenAIInstrumentation } from "@arizeai/openinference-instrumentation-openai";

const provider = registerOTel();
registerInstrumentations({
  instrumentations: [new OpenAIInstrumentation()],
  tracerProvider: provider,
});

For LiteLLM call paths and import pitfalls, see Provider instrumentation.

from uselemma_tracing import instrument_openai

instrument_openai()

Call through the module (litellm.acompletion, not from litellm import acompletion) when using LiteLLM so calls hit patched symbols — see Import and call-path pitfalls.

Getting Started

Tracing

Experiments

Integrations

Environment variables

Install dependencies

Register OpenTelemetry once at startup

Create a run

What is captured automatically vs manually

Optional: add OpenInference instrumentors

Next Steps

Getting Started

Tracing

Experiments

Integrations

​Environment variables

​Install dependencies

​Register OpenTelemetry once at startup

​Create a run

​What is captured automatically vs manually

​Optional: add OpenInference instrumentors

​Next Steps

Environment variables

Install dependencies

Register OpenTelemetry once at startup

Create a run

What is captured automatically vs manually

Optional: add OpenInference instrumentors

Next Steps