Struct ThreadTraceContext 

pub struct ThreadTraceContext { /* private fields */ }

No-op-capable handle for recording one thread in a rollout bundle. No-op capable trace handle for one thread in a rollout bundle.

Implementations

impl ThreadTraceContext

pub fn disabled() -> Self

Builds a context that accepts trace calls and records nothing.

pub fn start_root_or_disabled(metadata: ThreadStartedTraceMetadata) -> Self

Starts a root thread trace from CODEX_ROLLOUT_TRACE_ROOT, or disables tracing.

Trace startup is best-effort. A tracing failure must not make the Codex session unusable, because traces are diagnostic and can be enabled while debugging unrelated production failures.

pub fn start_root_in_root_for_test( root: &Path, metadata: ThreadStartedTraceMetadata, ) -> Result<Self>

Starts a root trace in a known directory.

This is public for tests that need replayable trace bundles without mutating process environment.

pub fn is_enabled(&self) -> bool

Returns whether this handle will write trace events.

Most methods have their own disabled fast path. Callers should branch on this only when preparing trace payloads would otherwise clone data the production path needs to move elsewhere.

pub fn start_child_thread_trace_or_disabled( &self, metadata: ThreadStartedTraceMetadata, ) -> Self

Starts a fresh child thread in this context’s rollout tree.

Callers should use ThreadTraceContext::disabled for resumed children: reusing the parent trace would emit a duplicate ThreadStarted event for an existing thread id and make the bundle unreplayable.

pub fn record_ended(&self, status: RolloutStatus)

Emits terminal trace events for graceful thread shutdown.

Spawned child sessions share their root bundle, so only the root thread end closes the rollout. Child thread ends update the child thread execution state without marking the whole bundle complete.

pub fn record_protocol_event(&self, event: &EventMsg)

Wraps selected protocol events as raw trace breadcrumbs.

High-volume stream deltas stay out of this wrapper; typed inference, tool, terminal, and code-mode hooks provide the canonical runtime data.

pub fn record_codex_turn_event(&self, default_turn_id: &str, event: &EventMsg)

Emits typed Codex turn lifecycle events from protocol lifecycle events.

pub fn record_tool_call_event( &self, codex_turn_id: impl Into<CodexTurnId>, event: &EventMsg, )

Emits typed runtime tool events from existing protocol lifecycle events.

These events are runtime observations on an already-dispatched tool. The dispatch trace records the caller-facing boundary; these payloads explain what Codex did while executing that boundary.

pub fn record_agent_result_interaction( &self, child_codex_turn_id: impl Into<CodexTurnId>, parent_thread_id: impl Into<AgentThreadId>, payload: &AgentResultTracePayload<'_>, )

Emits the v2 child-to-parent completion message as an explicit graph edge.

The notification is runtime delivery from a completed child turn into the parent’s mailbox, not a tool call executed by the child. Recording it directly preserves timing and source without making the reducer infer the edge from a later parent prompt snapshot.

pub fn record_codex_turn_started(&self, codex_turn_id: impl Into<CodexTurnId>)

Emits a turn-start lifecycle event.

Most production turn lifecycle wiring lives outside this PR layer, but trace-focused integration tests need a small explicit hook so reducer inputs remain valid without exercising the full session loop.

pub fn start_code_cell_trace( &self, codex_turn_id: impl Into<CodexTurnId>, runtime_cell_id: impl Into<String>, model_visible_call_id: impl Into<String>, source_js: impl Into<String>, ) -> CodeCellTraceContext

Starts a first-class code-mode cell lifecycle and returns its trace handle.

pub fn code_cell_trace_context( &self, codex_turn_id: impl Into<CodexTurnId>, runtime_cell_id: impl Into<String>, ) -> CodeCellTraceContext

Builds a trace handle for an already-started code-mode runtime cell.

pub fn start_tool_dispatch_trace( &self, invocation: impl FnOnce() -> Option<ToolDispatchInvocation>, ) -> ToolDispatchTraceContext

Starts one dispatch-level tool lifecycle and returns its trace handle.

invocation is lazy because adapting core tool objects into trace-owned payloads can clone large arguments. Disabled tracing should not pay that cost on the hot tool-dispatch path.

pub fn inference_trace_context( &self, codex_turn_id: impl Into<CodexTurnId>, model: impl Into<String>, provider_name: impl Into<String>, ) -> InferenceTraceContext

Builds reusable inference trace context for one Codex turn.

The returned context is intentionally not “an inference call” yet. Transport code owns retry/fallback attempts and calls start_attempt only after it has built the concrete request payload for that attempt.

pub fn compaction_trace_context( &self, codex_turn_id: impl Into<CodexTurnId>, compaction_id: impl Into<CompactionId>, model: impl Into<String>, provider_name: impl Into<String>, ) -> CompactionTraceContext

Builds remote-compaction trace context for one checkpoint.

Rollout tracing currently has a first-class checkpoint model only for remote compaction. The compact endpoint is a model-facing request whose output replaces live history, so it needs both request/response attempt events and a later checkpoint event when processed replacement history is installed.

pub fn start_mcp_call_trace( &self, tool_call_id: impl Into<ToolCallId>, ) -> McpCallTraceContext

Starts bridge correlation for one concrete MCP backend request.

Dispatch-level tool IDs remain compact and UI-friendly. This UUID is deliberately separate: it is only for cross-process log joins where a rollout-local counter would collide across samples.

Trait Implementations

impl Clone for ThreadTraceContext

fn clone(&self) -> ThreadTraceContext

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ThreadTraceContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.