Preserve causal trace links across API and provider boundaries

Use identities for different levels of work

A conversation can contain many turns, a turn can issue several tools and one tool can lead to multiple API or provider stages. Give those levels separate identities. A timestamp helps order observations, but two events near each other are not necessarily causally related.

Lupin’s shared trace model includes trace, conversation and turn identities, event and span identities, optional parent spans and bounded links such as operation, call, approval and provider request references. Keep the level of each identifier visible in application diagnostics instead of putting every value into an ambiguous request_id column.

Propagate context deliberately

The Lupin trace header helper carries validated conversation, turn, trace and channel context plus an optional parent span. Propagate it from the actual initiating workflow when calling the API. A helper must not invent a new trace on every retry or reuse one turn identity for unrelated queue jobs.

Trace headers correlate diagnostics; they do not authenticate the caller or select a workspace. The API derives ownership from its authenticated context. Never accept an organization from a diagnostic payload as authority, and do not broaden a caller’s resource access simply because it knows a valid-looking trace identifier.

Use parents for causation and links for evidence

A parent span describes a causal nesting relationship. An operation reference or provider request link connects evidence that may arrive later or outside that nesting. A callback can therefore join an existing operation’s diagnostic story without pretending it was a synchronous child that completed before the original request returned.

Keep retries identifiable as attempts of the same logical action. Preserve the operation link while recording per-attempt timing and transport results. Otherwise the timeline can either hide retries inside one event or incorrectly count each retry as another independent business action.

Protect immutable trace bindings

Lupin binds a stored trace to its conversation, turn and channel and rejects conflicting reuse. This prevents a later append from repurposing a trace ID for another story. A persistence conflict should lead the producer to inspect its context handling rather than overwrite the original binding.

Traces also carry source and outcome. An API handler can report its own request result without claiming that the entire agent turn completed. Keep those scopes distinct when combining agent-produced and API-produced events. Provider acceptance and a model’s completion statement remain different observations even when they share a trace.

Investigate gaps without inventing a chain

If a callback has no established linkage, do not attach it to the nearest visible turn. Check the saved operation and provider reference through authorized diagnostics. If linkage cannot be established, show it as unresolved evidence rather than creating a plausible but false timeline.

Use local fixtures for two concurrent turns, a retried request, an out-of-order callback and a conflicting trace binding. Verify that events remain under the correct workspace and turn. Also test missing and invalid trace headers: the business operation’s authorization must remain correct even when diagnostic correlation is unavailable.

Sources & verification

Reviewed against the checked-in Lupin implementation and official reference documentation on 2026-11-05. Operational examples are illustrative; no live paid action, provider mutation or external message was executed.

• OpenTelemetry traces and span context ↗Checked 2026-11-05
• Lupin authentication and resource policy ↗Checked 2026-11-05
• Lupin error reference ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.