Trace Parts of Your Code

A span represents a unit of work. It has a name, a start time, an end time, and optional attributes. Every trace is a tree of spans. Most of the time, the @observe decorator handles span creation automatically. But sometimes you need direct control:

Conditional tracing — Start a span only if certain conditions are met.
Dynamic naming — Determine the span name based on runtime data.
Long-running operations — Hold a span open across multiple function calls.
Non-function boundaries — Trace a block of code that isn’t a function.

Choosing the Right Method

It’s important to distinguish:

Creating a span (starts timing) vs activating a span (makes it the current parent for nesting)
Active spans (recommended) vs detached/manual spans (advanced)

Active spans automatically parent anything that runs inside them (including instrumented third-party libraries), because context propagation can attach child spans under the active span. Detached/manual spans are useful when you need to pass a span object around explicitly (or across async boundaries where call-stack parenting isn’t enough). Analogy:

Active span: create a folder and open it — new files go inside automatically.
Detached span: create a folder but don’t open it — new files won’t go inside unless you explicitly place them there.

Span Lifecycle

A manual span follows three steps:

Start — Create the span with a name. It becomes the “current” span, and any child spans nest under it.
Enrich — Add attributes, set input/output, record events or errors.
End — Close the span. This records the end time and sends the span to Laminar.

If you don’t end a span, it won’t appear in your traces. Use context managers (with in Python) or try/finally blocks to ensure spans always close, even when errors occur.

Common Options (and When to Use Them)

TypeScript
Python

Method	Creates span	Activates span	Ends span	Use when
`observe()`	✅	✅	✅	You’re tracing a function or request handler
`Laminar.startActiveSpan()`	✅	✅	❌	You need a parent span outside `observe()`
`Laminar.startSpan()`	✅	❌	❌	You want a detached span you’ll pass around
`Laminar.withSpan()`	❌	✅	❌ (optional)	You have a span object and want it to be current

import { Laminar } from '@lmnr-ai/lmnr';

const span = Laminar.startActiveSpan({ name: 'custom_operation' });
try {
  // Any spans created here become children of custom_operation
  await doWork();
} catch (error) {
  span.recordException(error as Error);
  throw error;
} finally {
  span.end();
}

See also: Laminar.startActiveSpan

Method	Creates span	Activates span	Ends span	Use when
`Laminar.start_as_current_span()`	✅	✅	✅	Default choice for tracing a block
`Laminar.start_active_span()`	✅	✅	❌	You want a span object but still need nesting
`Laminar.start_span()`	✅	❌	❌	You want a detached span you’ll pass around
`use_span()`	❌	✅	❌ (optional)	You have a span and want it to be current

from lmnr import Laminar

with Laminar.start_as_current_span(name="custom_operation") as span:
    try:
        do_work()
    except Exception as e:
        span.record_exception(e)
        raise
    # Span ends automatically on exit

In Python, prefer start_as_current_span() (context manager) or start_span() + use_span(). If you use start_active_span(), make sure you end the span in the same thread/async context it was created in—otherwise span hierarchy can become corrupted.

In the Laminar UI

Manually-created spans look the same as auto-instrumented spans: a node in the trace tree with timing and attributes.
If a span is active, any work executed inside it is parented underneath it automatically.

Span Types

Spans can have a type that affects how they appear in the Laminar UI:

DEFAULT — General-purpose span.
LLM — Language model call (enables token counts, cost tracking).
TOOL — Tool or function call within an agent.
EXECUTOR — Orchestration or routing logic.

Set the type when creating the span. LLM spans expect specific attributes for cost calculation—see LLM Cost Tracking and the SDK reference for span creation options.

Introduction

AI Security

Governance & RBAC

Observability

Choosing the Right Method

Span Lifecycle

Common Options (and When to Use Them)

In the Laminar UI

Span Types

​Choosing the Right Method

​Span Lifecycle

​Common Options (and When to Use Them)

​In the Laminar UI

​Span Types

Choosing the Right Method

Span Lifecycle

Common Options (and When to Use Them)

In the Laminar UI

Span Types