Local Recording Context Manager

record_traces_locally

The record_traces_locally context manager enables local, in-memory recording of any traces and spans created inside its block. This is useful for testing, debugging, or for programmatically inspecting your span/trace trees without sending data to the backend.

Basic usage

import opik

with opik.record_traces_locally() as storage:
    # Your instrumented code that creates traces/spans
    # e.g., functions decorated with @opik.track, manual opik.Opik().span()/trace(), integrations, etc.
    ...

    # Access in-memory results (automatically flushed before reading)
    span_models = storage.span_trees
    trace_models = storage.trace_trees

What it returns

The context yields a lightweight handle having these properties:

Each accessor flushes the Opik client to ensure all in-flight messages are processed before reading the local state.

No nested usage

Nested or concurrent usages within the same process are not supported. If a local recording is already active, entering another record_traces_locally block raises RuntimeError.

Notes

  • Uses the SDK’s local emulator to mirror what would be sent to the backend.

  • Data is kept in memory only for the life of the context. On exit, the local recorder is disabled and state is reset.

  • Ideal for task_span metrics validation, writing tests or ad-hoc scripts that need access to the span/trace tree structure.