Trace contract

Lemma traces are JSON trees delivered to POST /traces/ingest. A trace is one agent execution: the root record carries the current input, final output or error, agent name, optional thread/user context, and timing. All other work is child spans in trace.spans[], typed as span, generation, or tool, optionally nested via parent_id. The SDK builds this payload for you. This page defines what Lemma accepts, what each field means, how ingest normalizes it, and which fields unlock which product behavior.

One agent execution = one trace. LLM calls, tool calls, retrieval, and app logic are child spans inside that trace, not separate top-level traces.

Mental model

Concept	What it is	Client field
Trace	One end-to-end agent execution	The root `trace` object
Span	A unit of work inside the trace	`spans[]` entry with `type: "span"`
Generation	A single LLM call	`spans[]` entry with `type: "generation"`
Tool call	A single tool invocation	`spans[]` entry with `type: "tool"`

The SDK sends a trace record plus child spans. At ingest, Lemma creates a synthetic root span ({traceId}:root) that carries root-level fields for storage and display. Producers should target the trace record; they do not create the synthetic root themselves.

Requirement tiers

Tier	Meaning	Examples
Ingest	Required for a successful `201` response	Valid JSON, `project_id`, `trace.name`, named spans, unique span IDs
Semantic	Needed for Lemma product features	Root input/output-or-error, typed generations and tools, model and payloads, nesting, thread/user
High quality	Ideal instrumentation fidelity	Measured durations, complete span I/O, full per-call message history, causal nesting

Ingest accepts a name-only trace. Semantic fields are not HTTP-required, but without them Lemma can only render timing and a sparse tree. For the pedagogical ideal path, see Building high-quality traces.

Ingest payload

{
  "project_id": "00000000-0000-0000-0000-000000000000",
  "trace": {
    "id": "trace-id",
    "name": "support-agent",
    "input": "Where is my order #1843?",
    "output": "It ships tomorrow and arrives Friday.",
    "thread_id": "conversation-42",
    "user_id": "user-7",
    "release": "1.8.3",
    "started_at": "2026-07-13T20:00:00.000Z",
    "ended_at": "2026-07-13T20:00:02.410Z",
    "duration_ms": 2410,
    "spans": [
      {
        "id": "span-retrieve",
        "name": "retrieve-context",
        "type": "span",
        "input": { "query": "order 1843 status" },
        "output": { "count": 2 },
        "duration_ms": 412
      },
      {
        "id": "span-search",
        "parent_id": "span-retrieve",
        "name": "search_docs",
        "type": "tool",
        "input": { "query": "order 1843 status" },
        "output": [{ "id": "doc-1" }],
        "duration_ms": 183
      },
      {
        "id": "span-answer",
        "name": "answer",
        "type": "generation",
        "model": "gpt-4o",
        "input": [
          { "role": "system", "content": "You are a support agent." },
          { "role": "user", "content": "Where is my order #1843?" }
        ],
        "output": "It ships tomorrow and arrives Friday.",
        "duration_ms": 1870,
        "attributes": {
          "llm.input_messages.0.message.role": "system",
          "llm.input_messages.0.message.content": "You are a support agent."
        }
      }
    ]
  }
}

Envelope and validation

Field	Ingest rule
Body	Must be a JSON object
`project_id`	Required UUID
`trace`	Required object
`trace.name`	Required non-empty string
`trace.spans[].name`	Required non-empty string for each span
Span `id` values	Must be unique within the payload when provided
Authorization	Required; missing credentials return `401`

Successful ingest returns 201. Invalid shape returns 400. Missing trace.id or span id values are generated server-side. Missing or invalid spans[].type defaults to "span". Missing parent_id attaches the child under the synthetic root.

Delivery and retries

Deliver one complete trace when the execution (agent turn) finishes. This is required; patching a trace over time is not currently supported. Treat ingest as a single delivery, not an incremental merge API.

Required: one complete delivery per execution — root input/output, thread/user, and all child spans in one payload, sent when the turn is done.
Retries: re-sending the same payload with the same span IDs is idempotent; spans whose IDs already exist are skipped.
Not a merge API: omitted root fields do not preserve prior values. There is no field-level upsert, and patching a trace across calls is not supported.
Processing: after an idle window Lemma processes the trace once; a later successful re-delivery does not restart processTrace / extractSignals. Late new span IDs may still append for display.
Do not reuse one trace.id across conversation turns — see Instrumenting multi-turn agents.

Trace record

Field	Role
`id`	Stable identity for the execution; generated if omitted
`name`	Agent / workflow name used for grouping and filtering
`input`	Current user turn or execution entry point
`output`	Final answer on success
`error` / `status`	Failure message and `ERROR` status when the run fails
`started_at` / `ended_at` / `duration_ms`	Trace timing
`thread_id`	Groups multi-turn conversation traces
`user_id`	Per-user slicing
`release`	Optional deployed app version from the SDK client (`release` / `LEMMA_RELEASE`). Trimmed; empty, over 200 characters, or values with newlines, tabs, or carriage returns are omitted (unreleased)
`metadata`	Arbitrary JSON attached to the root
`spans`	Child work

Semantic guidance: include root input and either output or error. Without them, the dashboard can show timing but not what the user asked or whether the run succeeded. Callback traces set output from the return value unless you override it with trace.output(...). Uncaught exceptions mark the root as failed and still send the trace.

Child spans

Every child is a named object in trace.spans[].

Field	Role
`id`	Stable child identity; generated if omitted
`parent_id`	Parent span ID; omit to attach under the synthetic root
`name`	Human-readable operation name
`type`	`"span"`, `"generation"`, or `"tool"`
`input` / `output`	Operation arguments and result
`error` / `status`	Failure details; prefer these over inventing an output
`started_at` / `ended_at` / `duration_ms`	Timing
`model`	Generation model name
`usage`	Token counts when the provider supplied them (omit when unknown)
`attributes`	Flattened contract attributes and escape-hatch keys
`metadata`	Arbitrary JSON for the child

Typed children

Type	Use for	Semantic fields
`span`	Retrieval, ranking, planning, app logic	`input` + `output` (or `error`)
`generation`	One LLM call	`model`, prompt/messages, completion (or `error`), optional `usage`
`tool`	One tool invocation	tool `name`, arguments, result (or `error`)

Type is a discriminator. Setting model alone does not make a generation; set type: "generation".

Nesting

Children nest through parent_id. In TypeScript, recording from a span handle sets the parent automatically. In Python, pass parent_id explicitly on start_tool / start_generation / start_span when the child belongs under another span.

support-agent              ← trace record
├── retrieve-context       ← type: span
│   └── search_docs        ← type: tool, parent_id = retrieve-context
└── answer                 ← type: generation

Generations and message history

trace.input is the current user turn. A generation should record the full ordered message list sent to that LLM call, including system prompt, prior turns, tool results, and the current user message. Prefer both:

input — the prompt payload for that call
llmInputMessages / llm_input_messages — structured messages flattened into llm.input_messages.{index}.message.*

model is the primary model identifier. Native generation props such as llmProvider, llmInvocationParameters, and llmOutputMessages populate OpenInference-style attributes. Pass usage (camelCase in TypeScript, snake_case kwargs in Python) when the provider returns token counts — see Token usage.

Token usage

Generations may include a top-level usage object. Lemma does not invent token counts. Coverage semantics:

Provider behavior	SDK behavior
No usage supplied	Omit `usage` entirely (and omit usage attributes)
Usage includes zeros	Emit those zeros

Healthy zero ≠ missing instrumentation. Analytics uses absence vs explicit zero to decide whether a metric is unsupported or genuinely empty.

Wire format (ingest JSON)

{
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 340,
    "cache_read_input_tokens": 800,
    "cache_creation_input_tokens": 50,
    "reasoning_output_tokens": 120
  }
}

All fields are optional. Only include fields the provider actually returned.

TypeScript DX

trace.recordGeneration({
  name: "draft-reply",
  model: "gpt-4o",
  llmProvider: "openai",
  usage: {
    inputTokens: 1200,
    outputTokens: 340,
    cacheReadInputTokens: 800,
    cacheCreationInputTokens: 50,
    reasoningOutputTokens: 120,
  },
});

Python DX

trace.record_generation(
    name="draft-reply",
    model="gpt-4o",
    llm_provider="openai",
    input_tokens=1200,
    output_tokens=340,
    cache_read_input_tokens=800,
    cache_creation_input_tokens=50,
    reasoning_output_tokens=120,
)
# or: usage={"input_tokens": 1200, "output_tokens": 340, ...}

The SDK also flattens usage into span attributes using OTel GenAI names (gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, gen_ai.usage.cache_read.input_tokens, gen_ai.usage.cache_creation.input_tokens, gen_ai.usage.reasoning.output_tokens) plus OpenInference compatibility keys (llm.token_count.prompt, llm.token_count.completion). Do not derive user-facing aggregates or estimated cost in the SDK — the backend computes windowed Analytics quantities from this source telemetry.

Tools

Tool spans should carry:

name — stable tool identifier
input — arguments
output or error — result or failure
optional toolParameters / tool_parameters for the schema

Ingest uses tool_name when present, otherwise the span name, and normalizes tool I/O into tool-call aliases for display.

Errors

Record a failure on the exact span, generation, or tool where it happened:

Keep the input that led to the failure when it is safe to record.
Pass error instead of inventing an output.
End the failed child so timing is preserved.
Rethrow when the whole execution should fail; leave the root successful when the agent recovers.

For callback traces, uncaught exceptions automatically fail the root. If you catch at the root boundary, call trace.fail(error). For completed work, pass error to recordSpan / recordGeneration / recordTool (or the Python equivalents). For live handles, call .end({ error }) / .end(error=...).

TypeScript
Python

const tool = trace.startTool({
  name: "lookup_order",
  input: { orderId },
});

try {
  const order = await lookupOrder(orderId);
  tool.end({ output: order });
} catch (error) {
  tool.end({ error });
  throw error;
}

tool = trace.start_tool(
    name="lookup_order",
    input={"order_id": order_id},
)

try:
    order = lookup_order(order_id)
    tool.end(output=order)
except Exception as error:
    tool.end(error=error)
    raise

Timing

Duration resolution order:

Explicit duration_ms / durationMs when provided
Otherwise ended_at - started_at when both timestamps exist
Otherwise, for children with missing duration, Lemma allocates remaining parent time

Child duration inference:

Starts from the synthetic root and walks the parent → child tree
Explicit sibling durations claim time first
Siblings with duration_ms == null split the remaining parent duration equally
If explicit siblings already exceed the parent duration, omitted siblings receive 0
The same rule applies recursively when a child becomes a parent

Prefer live handles (startSpan / startTool / startGeneration) so .end(...) measures real elapsed time. One-shot record* helpers omit child duration when you do not pass it.

Client fields vs ingest normalization

Clients send first-class JSON fields. Ingest generates display and analysis aliases.

Client sends	Ingest normalizes to
`trace.input`	`input.value`, `ai.agent.input`
`trace.output`	`output.value`, `ai.agent.output`, and `ai.response.text` for strings
`trace.name`	`gen_ai.agent.name`, `ai.agent.name`
`trace.thread_id`	`lemma.thread_id`
`trace.user_id`	`user.id`, `enduser.id`
`type: "generation"`	`kind: "generation"`, `openinference.span.kind: "llm"`
`type: "tool"`	`kind: "tool"`, `openinference.span.kind: "tool"`, `tool.name`
`model`	`gen_ai.request.model`, `ai.model.id`, `model_name`
generation `input` / `output`	`input.value` / `output.value`
tool `input` / `output`	`input.value`, `output.value`, `ai.toolCall.args`, `ai.toolCall.result`
`error`	`error.message`, error status
native props / `attributes`	Flattened OpenInference-style attribute keys

Do not hand-build the normalized aliases unless you are bypassing the SDK. Prefer native SDK props and first-class fields.

SDK mapping

TypeScript
Python

Contract field	SDK API	Client field
Trace input	`lemma.trace({ input })`	`trace.input`
Trace output	Callback return value or `trace.output(output)`	`trace.output`
Trace duration	Measured automatically, `durationMs`, or `trace.end({ durationMs })`	`trace.duration_ms`
Agent name	`lemma.trace({ name })`	`trace.name`
Thread id	`threadId`	`trace.thread_id`
User id	`userId`	`trace.user_id`
Generation	`trace.recordGeneration(...)` / `startGeneration(...)`	`type: "generation"`
Generation model	`model`	`model`
Generation usage	`usage: { inputTokens, ... }`	`usage` (snake_case on the wire)
Generation content	`input`, `output`, `llmInputMessages`	`input`, `output`, attributes
Tool	`trace.recordTool(...)` / `startTool(...)`	`type: "tool"`
Tool args / result	`input`, `output`	`input`, `output`
Child duration	`durationMs` or live-handle `.end()`	`duration_ms`
Nesting	Span-handle record/start methods or `parentId`	`parent_id`
Error	thrown error, `trace.fail(error)`, or child `error`	`error`, `status`

Contract field	SDK API	Client field
Trace input	`lemma.trace(..., input=...)`	`trace.input`
Trace output	Callback return value or `trace.output(output)`	`trace.output`
Trace duration	Measured automatically or `duration_ms`	`trace.duration_ms`
Agent name	`lemma.trace("name", ...)`	`trace.name`
Thread id	`thread_id`	`trace.thread_id`
User id	`user_id`	`trace.user_id`
Generation	`trace.record_generation(...)` / `start_generation(...)`	`type: "generation"`
Generation model	`model`	`model`
Generation usage	`usage={...}` or `input_tokens=` / `output_tokens=` kwargs	`usage`
Generation content	`input`, `output`, `llm_input_messages`	`input`, `output`, attributes
Tool	`trace.record_tool(...)` / `start_tool(...)`	`type: "tool"`
Tool args / result	`input`, `output`	`input`, `output`
Child duration	`duration_ms` or live-handle `.end()`	`duration_ms`
Nesting	`parent_id` on `start_*` helpers	`parent_id`
Error	raised exception, `trace.fail(error)`, or child `error`	`error`, `status`

Native contract props

Use native props instead of hand-building flattened attribute names. In Python, use snake_case.

Common
Generation
Tool
Embedding
Reranker

SDK prop	Use on	Attribute key
`inputMimeType`	Span, generation, tool	`input.mime_type`
`outputMimeType`	Span, generation, tool	`output.mime_type`

SDK prop	Attribute key
`llmModelName`	`llm.model_name`
`llmProvider`	`llm.provider` (also sets `gen_ai.system` when `llmSystem` is unset)
`llmSystem`	`llm.system`, `gen_ai.system`
`usage`	`gen_ai.usage.*`, `llm.token_count.prompt` / `completion`
`llmInvocationParameters`	`llm.invocation_parameters`
`llmInputMessages`	`llm.input_messages.{index}.message.*`
`llmOutputMessages`	`llm.output_messages.{index}.message.*`
`llmTools`	`llm.tools`
`llmPromptTemplate`	`llm.prompt_template.template`
`llmPromptTemplateVariables`	`llm.prompt_template.variables`
`llmPromptTemplateVersion`	`llm.prompt_template.version`

SDK prop	Attribute key
`toolDescription`	`tool.description`
`toolParameters`	`tool.parameters`

SDK prop	Attribute key
`embeddingModelName`	`embedding.model_name`
`embeddingInvocationParameters`	`embedding.invocation_parameters`
`embeddingEmbeddings`	`embedding.embeddings`

SDK prop	Attribute key
`rerankerModelName`	`reranker.model_name`
`rerankerInputDocuments`	`reranker.input_documents.{index}.document.*`
`rerankerOutputDocuments`	`reranker.output_documents.{index}.document.*`

model also populates llm.model_name for generation records. Object and array attribute values are serialized where Lemma expects string-valued attributes. For fields without a native prop, pass raw attributes.

Provenance attributes (Lemma extensions)

Every emitted span includes SDK provenance so Analytics can attribute coverage gaps to an integration or language without provider-specific frontend logic:

Attribute	Values	Set by
`lemma.sdk.language`	`typescript` \| `python`	Core client
`lemma.sdk.integration`	`manual` \| `vercel-ai` \| `langchain` \| `openai-agents` \| `mastra`	Core defaults to `manual`; integrations override

These are Lemma-specific extensions (not OpenTelemetry GenAI canonical names).

Semantic requirements

Field	Why it matters
One shared `trace.id` for the whole execution	Otherwise one run scatters across unrelated traces
Root `input`	Shows what the user asked
Root `output` or `error`	Distinguishes success from failure
Stable `name`	Groups and filters by agent/workflow
Typed generations with model + content	Makes model calls inspectable
Provider identity (`llm.provider` / `gen_ai.system`)	Model, token, and estimated-cost breakdowns
Token `usage` when the provider supplies it	Token and estimated-cost Analytics; omit vs zero coverage
Typed tools with args + result/error	Makes tool behavior inspectable
Correct `parent_id` nesting	Preserves causality in the tree
`thread_id` for multi-turn work	Groups conversation turns
`user_id` when available	Enables per-user slicing
Measured `duration_ms` on root and generations	Root latency vs generation speed as distinct quantities

Issue detection

Complete, correctly typed trees improve classification and automated issue extraction. Root I/O, model fields, and tool payloads are not general ingest gates. Some environments may further restrict issue extraction to specific framework shapes; treat that as an environment policy, not as the base SDK contract.

Privacy

Redact secrets, credentials, and sensitive user data before tracing them. Framework integrations always record inputs, outputs, and error messages: without them a trace cannot show what a run consumed, produced, or why it failed.

Analytics telemetry

Required attributes for Analytics widgets and upgrade behavior.

Building high-quality traces

Bad → better → best examples for the ideal instrumentation path.

Instrument an agent

Build a complete Lemma trace one piece at a time.

Generations

Capture model, full messages, and completion.

Common issues

Diagnose missing spans, flat trees, and blank I/O.

Getting Started

Instrumentation

Integrations

Connections

Trace contract

Mental model

Requirement tiers

Ingest payload

Envelope and validation

Delivery and retries

Trace record

Child spans

Typed children

Nesting

Generations and message history

Token usage

Wire format (ingest JSON)

TypeScript DX

Python DX

Tools

Errors

Timing

Client fields vs ingest normalization

SDK mapping

Native contract props

Provenance attributes (Lemma extensions)

Semantic requirements

Issue detection

Privacy

Analytics telemetry

Building high-quality traces

Instrument an agent

Generations

Common issues

​Mental model

​Requirement tiers

​Ingest payload

​Envelope and validation

​Delivery and retries

​Trace record

​Child spans

​Typed children

​Nesting

​Generations and message history

​Token usage

​Wire format (ingest JSON)

​TypeScript DX

​Python DX

​Tools

​Errors

​Timing

​Client fields vs ingest normalization

​SDK mapping

​Native contract props

​Provenance attributes (Lemma extensions)

​Semantic requirements

​Issue detection

​Privacy

​Related pages

Analytics telemetry

Building high-quality traces

Instrument an agent

Generations

Common issues

Mental model

Requirement tiers

Ingest payload

Envelope and validation

Delivery and retries

Trace record

Child spans

Typed children

Nesting

Generations and message history

Token usage

Wire format (ingest JSON)

TypeScript DX

Python DX

Tools

Errors

Timing

Client fields vs ingest normalization

SDK mapping

Native contract props

Provenance attributes (Lemma extensions)

Semantic requirements

Issue detection

Privacy

Related pages