Span Attribute Reference

This page is the reference for setting Laminar-recognized OpenTelemetry attributes from a non-SDK exporter: foreign-language SDKs, browser code, custom instrumentations, internal trace adapters. If you are using @lmnr-ai/lmnr or lmnr (Python), the SDK already sets these attributes for you. Use this page when you ship OTLP directly to Laminar without the SDK and need the literal wire keys.

How attributes flow into Laminar

Spans arrive at Laminar as standard OTLP. Laminar reads three layers:

• Resource attributes on the tracer provider (service.name, service.version, deployment.environment).
• Span attributes on each span: span shape, LLM telemetry, GenAI semconv content.
• Trace-association attributes, which Laminar lifts off any span in the trace and stores once on the trace record (session, user, metadata, tags, trace type).

Trace-association attributes use an “any-span wins” merge: the first non-empty value Laminar sees during ingest is what the trace gets. The most predictable place to set them is the root span, set them once.

Span-shape attributes

Set on the span you want to control. All keys are namespaced under lmnr.span.*.

Key	Type	What it does
lmnr.span.type	string	Span type: DEFAULT, LLM, or TOOL. Drives transcript rendering and cost rollups. EXECUTOR, EVALUATOR, HUMAN_EVALUATOR, EVALUATION, CACHED are reserved for the evaluations framework; do not set them on application spans.
lmnr.span.input	string (JSON-stringified)	Populates the Input panel and the transcript-view inline preview. Stringify non-primitive values before setting.
lmnr.span.output	string (JSON-stringified)	Populates the Output panel and inline preview. Stringify non-primitive values.
lmnr.span.path	string array	Ordered span-name path from the trace root to this span (inclusive). Drives transcript rendering: subagent grouping, parent-chain reconstruction for partial traces, and the path-based clustering that powers the conversation view. The Laminar SDKs auto-fill this. Custom exporters either leave it unset (Laminar falls back to the OTel parent_span_id chain, which gives a less rich transcript) or fill it themselves to mirror what the SDK would emit.
lmnr.span.ids_path	string array	Span-id path from the trace root to this span (inclusive), aligned 1:1 with lmnr.span.path. Same load-bearing role as lmnr.span.path: set both or neither.
lmnr.span.parent_path	string array	Path of the parent span (lmnr.span.path minus the last element). Optional; only useful if you set the path yourself.
lmnr.span.parent_ids_path	string array	Span-id form of lmnr.span.parent_path. Optional; pair with lmnr.span.parent_path.
lmnr.span.instrumentation_source	string	Free-form label identifying the emitter (e.g. "javascript", "my-internal-adapter"). Surfaces in span metadata.
lmnr.span.sdk_version	string	Version of the emitter. Optional.
lmnr.span.language_version	string	Runtime version of the emitter. Optional.
lmnr.span.human_evaluator_options	string (JSON)	Used by HumanEvaluator(). See evaluations.

Setting lmnr.span.type = "LLM" is required for LLM-specific UI and cost rollups to render at all. A span with LLM type but no gen_ai.* content shows up in the LLM section but with an empty conversation panel. See LLM attributes below.

Trace-association attributes

These describe the trace, not the individual span. Set them once on the root span: Laminar lifts them onto the trace record at ingest time. Setting them on every span works but is wasteful.

Key	Type	What it does
lmnr.association.properties.session_id	string	Groups traces into a session.
lmnr.association.properties.user_id	string	Attaches a user id to the trace.
lmnr.association.properties.rollout_session_id	string	Used by the agent debugger for rollout grouping.
lmnr.association.properties.trace_type	string	Trace classification ("DEFAULT" / "EVALUATION"). Most callers leave this alone.
lmnr.association.properties.tags	string array	Span-level tags. Tags are unioned across every span in the trace (not root-only) and the union becomes the trace tag set.
lmnr.association.properties.metadata.<key>	primitive or JSON-stringified	Trace metadata: one attribute per key. Primitives (string, number, boolean, arrays of those) pass through; complex values must be JSON.stringifyd before set.

The metadata key shape mirrors what the Laminar SDK emits. To attach {environment: "prod", featureFlag: "new-algo", abVariant: {bucket: 3}} to a trace, set three attributes on the root span:

lmnr.association.properties.metadata.environment   = "prod"
lmnr.association.properties.metadata.featureFlag   = "new-algo"
lmnr.association.properties.metadata.abVariant     = "{\"bucket\":3}"

LLM attributes

Set these on a span where lmnr.span.type = "LLM".

Provider, model, tokens, cost

Concept	Wire key	Example
Provider	gen_ai.system	"openai"
Request model	gen_ai.request.model	"gpt-5-mini"
Response model	gen_ai.response.model	"gpt-5-mini-2025-04-01"
Input tokens	gen_ai.usage.input_tokens	1284
Output tokens	gen_ai.usage.output_tokens	162
Total tokens	llm.usage.total_tokens	1446
Input cost	gen_ai.usage.input_cost	0.0019
Output cost	gen_ai.usage.output_cost	0.0024
Total cost	gen_ai.usage.cost	0.0043

Cost is calculated from gen_ai.system + gen_ai.request.model + token counts. Without all three, cost stays at zero. Setting the explicit gen_ai.usage.*_cost keys overrides the calculated values. See LLM cost tracking for the supported provider names.

Prompts and completions

Use the OTel GenAI semconv message-array form. This is the convention Laminar recommends for new exporters.

Key	Description
gen_ai.input.messages	JSON-stringified [{role, parts: [...]}] array.
gen_ai.output.messages	JSON-stringified [{role, parts: [...]}] array.
gen_ai.system_instructions	System prompt, prepended to the input messages as a synthetic system entry.

Each parts entry is one of {type: "text", content}, {type: "thinking", content}, {type: "tool_call", id, name, arguments}, {type: "tool_call_response", id, response}, {type: "uri", uri}, {type: "blob", blob, mimeType}. Laminar preserves the message shape end-to-end and the frontend renders each part inline.

The indexed gen_ai.prompt.{i}.* / gen_ai.completion.{i}.* shape (older OpenLLMetry / OpenInference convention) is still ingested for backwards compatibility but is deprecated. New exporters should emit the semconv form above.

Tool definitions

Key	Description
gen_ai.tool.definitions	JSON-stringified array of the tools the model was given for this call. Each entry is {type, function: {name, description, parameters}} (OpenAI shape) or the provider-equivalent shape with name / description / input_schema. Renders as the tools dropdown on the LLM span.

The older llm.request.functions.{i}.{name,description,parameters} indexed form is still ingested for backwards compatibility but is deprecated. New exporters should emit gen_ai.tool.definitions.

Where to put each attribute

Scope	OTel placement	Use for
Process-wide	Resource on the tracer provider	service.name, service.version, deployment.environment, app-wide constants
Trace-wide	Root span, via lmnr.association.properties.*	session, user, tags, metadata
Per-span, known at creation	tracer.startSpan(name, { attributes })	lmnr.span.type, lmnr.span.input, gen_ai.system, gen_ai.request.model
Per-span, known after work runs	span.setAttributes({...})	lmnr.span.output, gen_ai.response.model, token counts

Resource-level attributes are sent once per batch and apply to every span in that batch; putting service.name on each span instead is wasteful and harder to filter. For trace-association attributes, root-span placement is simpler than every-span placement and produces the same result.

Worked example: a minimal correct trace without the SDK

The example below uses only @opentelemetry/api and @opentelemetry/sdk-trace-*, no @lmnr-ai/lmnr import. The Python snippet uses the same plain OTel APIs. Both build the same trace shape: an outer agent.run span with session metadata, a child llm.chat LLM span with full GenAI attributes, and a child tool.execute TOOL span.

TypeScript

import { trace, context, SpanStatusCode } from "@opentelemetry/api";
import { resourceFromAttributes } from "@opentelemetry/resources";
import {
  NodeTracerProvider,
  BatchSpanProcessor,
} from "@opentelemetry/sdk-trace-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto";
import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: "my-agent",
  }),
  spanProcessors: [
    new BatchSpanProcessor(
      new OTLPTraceExporter({
        url: "https://api.lmnr.ai:443/v1/traces",
        headers: {
          Authorization: `Bearer ${process.env.LMNR_PROJECT_API_KEY}`,
        },
      }),
    ),
  ],
});
provider.register();

const tracer = trace.getTracer("my-agent", "0.1.0");

const root = tracer.startSpan("agent.run", {
  attributes: {
    // Laminar-specific
    "lmnr.span.type": "DEFAULT",
    "lmnr.span.input": JSON.stringify({ goal: "book a flight to NYC" }),

    // Trace-association: set ONCE on the root span
    "lmnr.association.properties.session_id": "sess-9f21",
    "lmnr.association.properties.user_id": "u_42",
    "lmnr.association.properties.tags": ["beta", "internal"],
    "lmnr.association.properties.metadata.environment": "production",
    "lmnr.association.properties.metadata.region": "us-west",
  },
});

await context.with(trace.setSpan(context.active(), root), async () => {
  // Child LLM span with the full required GenAI set.
  const llm = tracer.startSpan("llm.chat", {
    attributes: {
      "lmnr.span.type": "LLM",
      // GenAI semconv (OTel-defined keys)
      "gen_ai.system": "openai",
      "gen_ai.request.model": "gpt-5-mini",
      "gen_ai.input.messages": JSON.stringify([
        {
          role: "user",
          parts: [{ type: "text", content: "Find me a flight to NYC tomorrow." }],
        },
      ]),
    },
  });
  // ... call your provider, capture the response ...
  llm.setAttributes({
    "gen_ai.response.model": "gpt-5-mini-2025-04-01",
    "gen_ai.usage.input_tokens": 18,
    "gen_ai.usage.output_tokens": 42,
    "gen_ai.output.messages": JSON.stringify([
      {
        role: "assistant",
        parts: [{ type: "text", content: "I found 3 flights..." }],
      },
    ]),
    "lmnr.span.output": JSON.stringify({
      flights: [{ id: "AA101" }, { id: "DL202" }, { id: "UA303" }],
    }),
  });
  llm.setStatus({ code: SpanStatusCode.OK });
  llm.end();

  // Child TOOL span: arguments and return value go on input/output.
  const tool = tracer.startSpan("search_flights", {
    attributes: {
      "lmnr.span.type": "TOOL",
      "lmnr.span.input": JSON.stringify({
        origin: "SFO",
        destination: "JFK",
        date: "2026-05-19",
      }),
    },
  });
  // ... call your tool ...
  tool.setAttribute(
    "lmnr.span.output",
    JSON.stringify([{ id: "AA101", price: 412.5 }]),
  );
  tool.setStatus({ code: SpanStatusCode.OK });
  tool.end();
});

root.setStatus({ code: SpanStatusCode.OK });
root.end();
await provider.forceFlush();

Python

import json
import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.semconv.attributes.service_attributes import SERVICE_NAME
from opentelemetry.trace.status import Status, StatusCode

provider = TracerProvider(
    resource=Resource.create({SERVICE_NAME: "my-agent"}),
)
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://api.lmnr.ai:8443/v1/traces",
            headers={
                "authorization": f"Bearer {os.environ['LMNR_PROJECT_API_KEY']}",
            },
        ),
    ),
)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("my-agent", "0.1.0")

with tracer.start_as_current_span(
    "agent.run",
    attributes={
        "lmnr.span.type": "DEFAULT",
        "lmnr.span.input": json.dumps({"goal": "book a flight to NYC"}),
        "lmnr.association.properties.session_id": "sess-9f21",
        "lmnr.association.properties.user_id": "u_42",
        "lmnr.association.properties.tags": ["beta", "internal"],
        "lmnr.association.properties.metadata.environment": "production",
        "lmnr.association.properties.metadata.region": "us-west",
    },
) as root:
    with tracer.start_as_current_span(
        "llm.chat",
        attributes={
            "lmnr.span.type": "LLM",
            "gen_ai.system": "openai",
            "gen_ai.request.model": "gpt-5-mini",
            "gen_ai.input.messages": json.dumps([
                {
                    "role": "user",
                    "parts": [
                        {"type": "text", "content": "Find me a flight to NYC tomorrow."},
                    ],
                },
            ]),
        },
    ) as llm:
        # ... call your provider, capture the response ...
        llm.set_attributes({
            "gen_ai.response.model": "gpt-5-mini-2025-04-01",
            "gen_ai.usage.input_tokens": 18,
            "gen_ai.usage.output_tokens": 42,
            "gen_ai.output.messages": json.dumps([
                {
                    "role": "assistant",
                    "parts": [{"type": "text", "content": "I found 3 flights..."}],
                },
            ]),
            "lmnr.span.output": json.dumps(
                {"flights": [{"id": "AA101"}, {"id": "DL202"}]},
            ),
        })
        llm.set_status(Status(StatusCode.OK))

    with tracer.start_as_current_span(
        "search_flights",
        attributes={
            "lmnr.span.type": "TOOL",
            "lmnr.span.input": json.dumps({
                "origin": "SFO",
                "destination": "JFK",
                "date": "2026-05-19",
            }),
        },
    ) as tool:
        # ... call your tool ...
        tool.set_attribute(
            "lmnr.span.output",
            json.dumps([{"id": "AA101", "price": 412.5}]),
        )
        tool.set_status(Status(StatusCode.OK))

    root.set_status(Status(StatusCode.OK))

provider.force_flush()

GenAI keys (gen_ai.*) are part of the OpenTelemetry GenAI semantic conventions; everything under lmnr.* is Laminar-specific.

Anti-patterns

• Setting lmnr.association.properties.session_id on every span. Set it once on the root; Laminar lifts it onto the trace at ingest. Repeating it everywhere wastes attribute bytes.
• Putting service.name or app version on each span. These are Resource attributes. Set them on the tracer provider’s Resource so they’re emitted once per batch.
• Setting lmnr.span.type = "EXECUTOR" on application code. EXECUTOR is reserved for auto-instrumentation and the evaluations framework. Use DEFAULT or TOOL.
• Setting LLM token counts without gen_ai.system + gen_ai.request.model. Cost stays at zero. The provider name and request model are required to look up pricing.
• Setting lmnr.span.type = "LLM" but omitting prompt and completion attributes. The span renders as an LLM call but the conversation panel is empty. Emit gen_ai.input.messages and gen_ai.output.messages.
• Passing non-primitive attribute values directly. OTel attribute values are limited to string | number | boolean | string[] | number[] | boolean[]. For lmnr.span.input, lmnr.span.output, per-message content, or non-primitive metadata values, JSON.stringify first.

Transports for /v1/traces

The Laminar cloud (api.lmnr.ai) and self-hosted backends accept three OTLP transports:

• OTLP/gRPC on :8443 (cloud) / :8001 (self-hosted): the recommended path.
• OTLP/HTTP+protobuf on :443 (cloud) / :8000 (self-hosted): Content-Type: application/x-protobuf.
• OTLP/HTTP+JSON on :443 (cloud) / :8000 (self-hosted): Content-Type: application/json. Useful for browser SDKs and other runtimes that don’t have a protobuf encoder available; spec quirks (hex or base64 IDs, decimal-stringified fixed64, enum-name strings) are accepted.

Pick whichever your runtime supports best. Attribute semantics on the wire are identical across transports.

What’s next

OpenTelemetry transport setup

Endpoints, ports, headers, and the gRPC vs HTTP comparison.

Span types

What DEFAULT, LLM, and TOOL render to in the transcript view.

LLM cost tracking

Required gen_ai.* attributes and supported provider names.

Metadata

Trace-level metadata, including the wire key for non-SDK exporters.