Batching and update operations

By default, the Opik Python SDK batches create requests for traces and spans to improve ingestion throughput. While this is the recommended setting for most use cases, it can cause issues when you update a span or trace shortly after creating it.

What can go wrong

When batching is enabled, create requests are queued and sent to the server in batches. If you call .end() or .update() on a span or trace before its batched create request has been flushed, the update may arrive at the server first. Since the server has no record of that span or trace yet, the update is silently dropped and the data is lost.

This only affects the low-level client API (client.trace(), client.span(), client.update_trace(), client.update_span(), .end(), .update()). The @track decorator and start_as_current_span context manager handle lifecycle automatically and are not affected.

Recommended approaches

Use decorators or context managers (recommended)

The safest way to create and manage spans and traces is through the @track decorator or start_as_current_span context manager. These handle the full lifecycle — creation, data capture, and finalization — in a single operation with no separate update step.

1
import opik
2
3
# Using the @track decorator
4
@opik.track
5
def my_llm_call(prompt: str) -> str:
6
    response = call_llm(prompt)
7
    return response
8
9
# Using context managers
10
with opik.start_as_current_span(name="my_span") as span:
11
    result = call_llm("Hello")

Re-send the full payload to overwrite

If you need to use the low-level client API, you can call client.trace() or client.span() again with the same ID and the complete data. The backend treats each create request as an upsert — if a trace or span with that ID already exists, the new payload overwrites the previous one entirely. This avoids the race condition because you are not relying on a separate update arriving after the original create.

1
import datetime
2
import opik
3
4
client = opik.Opik()
5
6
# First call — creates the trace (batched)
7
trace = client.trace(
8
    name="my_trace",
9
    input={"prompt": "Hello"},
10
)
11
12
# ... do work ...
13
14
# Second call with the same ID — overwrites the trace with full data
15
client.trace(
16
    id=trace.id,
17
    name="my_trace",
18
    input={"prompt": "Hello"},
19
    output={"response": "Hi there"},
20
    end_time=datetime.datetime.now(datetime.timezone.utc),
21
)

This also works for spans — call client.span() with the same id and trace_id to overwrite.

Disable batching

If your workflow requires creating spans and then updating them shortly after (for example, to add output data that is only available after an async operation completes), you can disable batching. This ensures each create request is sent immediately, so subsequent updates will always find the span on the server.

1
import opik
2
3
client = opik.Opik(batching=False)
4
5
trace = client.trace(name="my_trace", input={"prompt": "Hello"})
6
span = trace.span(name="llm_call", input={"prompt": "Hello"})
7
8
# Safe to call .end() because the create was sent immediately
9
span.end(output={"response": "Hi there"})
10
trace.end(output={"response": "Hi there"})

Suppress the warning

If you are calling .end() or .update() well after creation (for example, after a long-running operation completes), the batched create will have already been flushed and there is no risk of data loss. In this case, you can suppress the warning by setting an environment variable:

$
export OPIK_SUPPRESS_BATCHING_UPDATE_WARNING=true

Or in your Opik configuration file (~/.opik.config):

1
[opik]
2
suppress_batching_update_warning = true

Use integrations

All Opik integrations (LangChain, LlamaIndex, DSPy, OpenAI, Anthropic, and others) handle span and trace lifecycle internally and are not affected by this issue. If you are using an integration, no changes are needed.