Tracing Modules

This page documents internal tracing modules for contributor visibility. These underscored module paths are intentionally unstable.

Observed Event Additions

Recent tracing additions emit payload-observation events at key boundaries:

• ModelRequestObserved

• ModelResponseObserved

• ToolInvocationObserved

• ToolResultObserved

• WorkflowStepContextObserved

• WorkflowStepResultObserved

These events are additive; existing run/model/tool span events remain unchanged.

Payload Redaction and Preview Policy

Observed payload events apply a safe-default policy before writing:

• Sensitive keys are recursively masked (for example api_key, token, authorization, password, secret, access_token, refresh_token).

• Long string fields are truncated to bounded previews for practical trace size.

Trace tracer configuration and sink construction.

class design_research_agents._tracing._config.Tracer(*, enabled=True, trace_dir=PosixPath('traces'), enable_jsonl=True, enable_console=True, console_stream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

Explicitly configured tracer dependency injected into runtimes.

build_sinks(*, trace_path)

Build concrete sinks for this tracer configuration.

Parameters:

trace_path – Optional JSONL path returned by build_trace_path.

Returns:

Concrete sink instances enabled by this tracer configuration.

build_trace_path(*, run_id)

Build a trace JSONL path for one run when JSONL sink is enabled.

Parameters:

run_id – Request or run identifier used in the trace filename.

Returns:

JSONL output path for the run, or None when JSONL output is disabled.

console_stream

Stream used for console trace output.

enable_console

Whether console trace output should be emitted.

enable_jsonl

Whether JSONL trace files should be emitted.

enabled

Whether tracing is enabled for this tracer instance.

resolve_latest_trace_path(request_id)

Resolve latest emitted JSONL trace path for one request id.

Parameters:

request_id – Request identifier used in trace filenames.

Returns:

Latest matching trace file path, or None.

run_callable(*, agent_name, request_id, input_payload, function, dependencies=None)

One callable wrapped in explicit trace session lifecycle.

Parameters:

• agent_name – Delegate name used in trace metadata.

• request_id – Request id used for trace run and file naming.

• input_payload – Input payload metadata for trace run start.

• function – Zero-argument callable to execute.

• dependencies – Optional dependency mapping for trace metadata.

Returns:

Function return value.

trace_dir

Directory where JSONL trace files are written.

trace_info(request_id)

Return JSON-serializable trace metadata for one request id.

Parameters:

request_id – Request identifier associated with the trace run.

Returns:

Trace metadata payload.

Trace session context management.

class design_research_agents._tracing._context.TraceScope(*, session, span_id, is_root, trace_token=None, span_token=None, agent_name=None)

Context manager payload for active trace scopes.

agent_name

Stored agent_name value.

is_root

Stored is_root value.

session

Stored session value.

span_id

Stored span_id value.

span_token

Stored span_token value.

trace_token

Stored trace_token value.

design_research_agents._tracing._context.current_span_id()

Return the current active span id if one is set.

Returns:

Active span id, or None when no span is active.

design_research_agents._tracing._context.current_trace_session()

Return the current trace session when active.

Returns:

Active trace session, or None when tracing is inactive.

design_research_agents._tracing._context.finish_trace_run(scope, *, result=None, error=None)

Finish a trace run scope with success or failure metadata.

Parameters:

• scope – Trace scope returned by start_trace_run.

• result – Optional result payload for success metadata.

• error – Optional error string for failure metadata.

design_research_agents._tracing._context.start_trace_run(*, agent_name, request_id, input_payload, dependencies, tracer=None)

Start a trace run scope or nested agent span.

Parameters:

• agent_name – Delegate name for trace metadata.

• request_id – Request identifier for the run.

• input_payload – Normalized input payload mapping.

• dependencies – Dependency payload mapping.

• tracer – Explicit tracer dependency. When None tracing is disabled.

Returns:

Trace scope when tracing is enabled, otherwise None.

Trace event emitters for model calls, tools, and decisions.

design_research_agents._tracing._emitters.emit_continuation_decision(*, step, should_continue, reason, source)

Emit a continuation decision event.

Parameters:

• step – Step index for the decision.

• should_continue – Decision outcome.

• reason – Optional reason text from the model or heuristic.

• source – Decision source label.

design_research_agents._tracing._emitters.emit_guardrail_decision(*, guardrail, decision, reason, details=None)

Emit a guardrail decision event.

Parameters:

• guardrail – Guardrail identifier.

• decision – Decision outcome label.

• reason – Optional reason text for the decision.

• details – Optional structured decision metadata.

design_research_agents._tracing._emitters.emit_model_request_observed(*, source, model, request_payload, metadata=None)

Emit one model request-observation event on the current span.

Parameters:

• source – Source label for where the request was observed.

• model – Model identifier when available.

• request_payload – Raw request payload observed at this boundary.

• metadata – Optional extra attributes to include.

design_research_agents._tracing._emitters.emit_model_response_observed(*, source, response_payload=None, error=None, metadata=None)

Emit one model response-observation event on the current span.

Parameters:

• source – Source label for where the response was observed.

• response_payload – Raw response payload observed at this boundary.

• error – Optional error text when the call failed.

• metadata – Optional extra attributes to include.

design_research_agents._tracing._emitters.emit_model_selection_decision(*, model_id, provider, rationale, policy_id, policy_config, catalog_signature, intent, constraints, hardware_profile, candidate_count)

Emit a model selection decision event.

Parameters:

• model_id – Selected model identifier.

• provider – Selected model provider.

• rationale – Selection rationale text.

• policy_id – Policy identifier used for selection.

• policy_config – Policy configuration used for selection.

• catalog_signature – Catalog signature used in selection.

• intent – Intent payload used for selection.

• constraints – Constraints payload used for selection.

• hardware_profile – Hardware profile snapshot used for selection.

• candidate_count – Number of candidates considered.

design_research_agents._tracing._emitters.emit_model_token(span_id, *, delta_text)

Emit a model-call token event.

Parameters:

• span_id – Span id for the model call.

• delta_text – Incremental text delta from the model.

design_research_agents._tracing._emitters.emit_router_decision(*, source, alternatives, selected_tool_name, selected_index, reason, parsed_route)

Emit a router decision event.

Parameters:

• source – Decision source label (e.g. “schema” or “fallback”).

• alternatives – Available alternative tool names.

• selected_tool_name – Selected tool name, if any.

• selected_index – Selected alternative index, if any.

• reason – Optional reason text from the model or heuristic.

• parsed_route – Parsed route payload when available.

design_research_agents._tracing._emitters.emit_tool_invocation_observed(*, tool_name, source_id, request_id, tool_input, dependency_keys, metadata=None)

Emit one tool invocation-observation event on the current span.

Parameters:

• tool_name – Routed tool name.

• source_id – Source identifier where invocation is routed.

• request_id – Invocation request id.

• tool_input – Tool input payload observed before invocation.

• dependency_keys – Sorted dependency keys visible to the tool.

• metadata – Optional extra attributes to include.

design_research_agents._tracing._emitters.emit_tool_result_observed(*, tool_name, source_id, ok, result_payload=None, error=None, metadata=None)

Emit one tool result-observation event on the current span.

Parameters:

• tool_name – Routed tool name.

• source_id – Source identifier where invocation was routed.

• ok – Tool success flag when available.

• result_payload – Tool result payload or partial metadata.

• error – Optional failure message.

• metadata – Optional extra attributes to include.

design_research_agents._tracing._emitters.emit_tool_selection_decision(*, source, tool_name, reason, parsed_tool_call)

Emit a tool selection decision event.

Parameters:

• source – Decision source label (e.g. “schema” or “fallback”).

• tool_name – Selected tool name.

• reason – Optional reason text from the model or heuristic.

• parsed_tool_call – Parsed tool call payload when available.

design_research_agents._tracing._emitters.emit_workflow_step_context(*, step_id, step_type, context)

Emit workflow step context observed before execution.

Parameters:

• step_id – Step identifier.

• step_type – Step-kind label.

• context – Full context mapping visible to the step.

design_research_agents._tracing._emitters.emit_workflow_step_result(*, step_id, step_type, status, success, output, error, metadata)

Emit workflow step result observed after execution.

Parameters:

• step_id – Step identifier.

• step_type – Step-kind label.

• status – Result status.

• success – Result success flag.

• output – Step output payload.

• error – Optional error text.

• metadata – Result metadata payload.

design_research_agents._tracing._emitters.fail_tool_call(span_id, *, tool_name, error)

Emit a tool-call failure event.

Parameters:

• span_id – Span id for the tool call.

• tool_name – Tool identifier being invoked.

• error – Error string describing the failure.

design_research_agents._tracing._emitters.finish_model_call(span_id, *, response=None, error=None, model=None)

Emit a model-call completion event.

Parameters:

• span_id – Span id for the model call.

• response – Optional response payload for success metadata.

• error – Optional error string for failure metadata.

• model – Optional model identifier when no response is available.

design_research_agents._tracing._emitters.finish_tool_call(span_id, *, tool_name, result)

Emit a tool-call completion event.

Parameters:

• span_id – Span id for the tool call.

• tool_name – Tool identifier being invoked.

• result – Tool result payload or metadata.

design_research_agents._tracing._emitters.start_model_call(*, model, messages, params, metadata=None)

Emit a model-call start event and return the span id.

Parameters:

• model – Model identifier for the call.

• messages – Message payloads sent to the model.

• params – Provider-neutral generation params.

• metadata – Optional extra attributes to include on the span.

Returns:

Span id for the model call, or None when tracing is disabled.

design_research_agents._tracing._emitters.start_tool_call(*, tool_name, tool_input, request_id, dependencies)

Emit a tool-call start event and return the span id.

Parameters:

• tool_name – Tool identifier being invoked.

• tool_input – Tool input payload mapping.

• request_id – Request identifier for tracing.

• dependencies – Dependency payload mapping for the tool.

Returns:

Span id for the tool call, or None when tracing is disabled.

Trace event models plus run-scoped span bookkeeping.

class design_research_agents._tracing._session.TraceEvent(*, event_type, run_id, span_id, parent_span_id, timestamp, timestamp_ms, duration_ms=None, attributes=<factory>, event_index=None)

Normalized trace event payload.

attributes

Normalized event-attribute payload.

duration_ms

Elapsed duration for completed spans, when known.

event_index

Monotonic sequence number within the trace session.

event_type

Normalized event type name.

parent_span_id

Parent span identifier, when the event is nested.

run_id

Run identifier that owns the event.

span_id

Span identifier associated with the event.

timestamp

ISO 8601 UTC timestamp for event emission.

timestamp_ms

Unix timestamp in milliseconds.

to_dict()

Return JSON-serializable dictionary representation.

Returns:

Normalized trace event mapping.

class design_research_agents._tracing._session.TraceSession(*, run_id, sinks)

Run-scoped trace session tracking open spans and sinks.

Initialize a trace session with a run id and sinks.

Parameters:

• run_id – Run identifier for this trace session.

• sinks – Trace sinks that will receive emitted events.

close()

Close all sinks associated with this session.

emit_event(event_type, *, span_id, parent_span_id, attributes, duration_ms=None)

Emit a standalone event payload to all sinks.

Parameters:

• event_type – Event type label.

• span_id – Span identifier for the event.

• parent_span_id – Optional parent span id.

• attributes – Event attributes payload.

• duration_ms – Optional event duration in milliseconds.

emit_span_event(event_type, *, span_id, attributes)

Emit an event tied to an existing span.

Parameters:

• event_type – Event type label for the span event.

• span_id – Span identifier for the event.

• attributes – Event attributes payload.

finish_span(event_type, *, span_id, attributes)

Finish a span and emit a completion event with duration.

Parameters:

• event_type – Event type label for the span completion.

• span_id – Span identifier to close.

• attributes – Event attributes payload.

start_span(event_type, *, parent_span_id, attributes)

Open a new span and emit its start event.

Parameters:

• event_type – Event type label for the span start.

• parent_span_id – Optional parent span id.

• attributes – Event attributes payload.

Returns:

Generated span id.

Trace sinks for JSONL and console output.

class design_research_agents._tracing._sinks.ConsoleTraceSink(stream=None)

Pretty streaming console sink for trace events.

Initialize a console sink that writes to the given stream.

Parameters:

stream – Optional stream to write console output to.

close()

Flush and close any open streaming output.

emit(event)

Render one event to the console stream.

Parameters:

event – Normalized trace event payload mapping.

class design_research_agents._tracing._sinks.JSONLTraceSink(path)

Append-only JSONL sink for trace events.

Initialize a JSONL sink that appends to the given path.

Parameters:

path – Output path for the JSONL trace file.

close()

Close the underlying file handle.

emit(event)

Write one event to the JSONL file.

Parameters:

event – Normalized trace event payload mapping.

class design_research_agents._tracing._sinks.TraceSink(*args, **kwargs)

Protocol for trace sinks that consume normalized event payloads.

close()

Finalize and release sink resources.

emit(event)

Handle one trace event payload.

Parameters:

event – Normalized trace event payload mapping.

Shared helpers for trace serialization, redaction, and formatting.

Simple trace-analysis harness for JSONL trace artifacts.

design_research_agents._tracing._analysis.analyze_trace_dir(*, trace_dir, glob_pattern='run_*.jsonl', top_n=10)

Analyze trace JSONL files under one directory.

design_research_agents._tracing._analysis.cast_mapping(value)

Cast a generic mapping into string-keyed object mapping.

design_research_agents._tracing._analysis.main(argv=None)

Trace-analysis CLI.