Threads & context

Set trace-level context when you open the trace.

Threads

When one user has a back-and-forth with your agent, each turn is its own trace. Give related turns the same threadId so Lemma groups them into one conversation.

TypeScript
Python

await lemma.trace(
  {
    name: "support-agent",
    input: userMessage,
    threadId: conversationId,
  },
  async (trace) => {
    return runAgent(userMessage, trace);
  },
);

async def run(trace):
    return await run_agent(user_message, trace)

await lemma.async_trace(
    "support-agent",
    run,
    input=user_message,
    thread_id=conversation_id,
)

Users

TypeScript
Python

await lemma.trace(
  {
    name: "support-agent",
    input: userMessage,
    threadId: conversationId,
    userId: user.id,
  },
  async (trace) => {
    return runAgent(userMessage, trace);
  },
);

async def run(trace):
    return await run_agent(user_message, trace)

await lemma.async_trace(
    "support-agent",
    run,
    input=user_message,
    thread_id=conversation_id,
    user_id=user.id,
)

Metadata

Attach any custom keys on the trace or a child span. There is no reserved set — firm.slug, plan, or any other key works. Ingest copies each key onto that span as an attribute, so you can filter with attr.<key>:<value>. Use dotted string keys, not nested objects. metadata: { "firm.slug": "acme" } becomes the attribute firm.slug. metadata: { firm: { slug: "acme" } } becomes one object-valued firm attribute and will not filter cleanly.

TypeScript
Python

await lemma.trace(
  {
    name: "support-agent",
    input: userMessage,
    metadata: {
      "firm.slug": "acme",
      plan: "enterprise",
    },
  },
  async (trace) => runAgent(userMessage, trace),
);

lemma.trace(
    "support-agent",
    lambda trace: run_agent(user_message, trace),
    input=user_message,
    metadata={"firm.slug": "acme", "plan": "enterprise"},
)

Filter those traces with attr.firm.slug:acme.

To keep staging data out of production, use a separate Lemma project. The SDK ingest path always stores service_name: "lemma-sdk"; set a custom service name through the OTLP resource service.name.

Reference

Context	SDK option	Client field	Ingest normalizes to
Agent name	`name`	`trace.name`	`gen_ai.agent.name`, `ai.agent.name`
Thread / conversation	`threadId` / `thread_id`	`trace.thread_id`	`lemma.thread_id`
User	`userId` / `user_id`	`trace.user_id`	`user.id`, `enduser.id`
Metadata	`metadata`	`trace.metadata` / `spans[].metadata`	Each key becomes a span attribute

See the trace contract for how each field is sent and normalized.

Next steps

Trace contract

What clients send, what ingest requires, and what Lemma normalizes.

Building high-quality traces

The ideal instrumentation path, with bad → better → best examples.

Getting Started

Instrumentation

Integrations

Connections

Threads & context

Threads

Users

Metadata

Reference

Next steps

Trace contract

Building high-quality traces

​Threads

​Users

​Metadata

​Reference

​Next steps

Trace contract

Building high-quality traces

Threads

Users

Metadata

Reference

Next steps