Skip to content

docs: add OrcaReplay to external tracing processors list - #5043

Draft
xizhuomengcontin wants to merge 1 commit into
openai:mainfrom
xizhuomengcontin:docs/orcareplay-tracing-processor
Draft

xizhuomengcontin wants to merge 1 commit into
openai:mainfrom
xizhuomengcontin:docs/orcareplay-tracing-processor

Conversation

@xizhuomengcontin

Copy link
Copy Markdown

Summary

Adds OrcaReplay to the existing external tracing processors list — one line, docs/tracing.md.

The published orcareplay-openai-agents implements the SDK's own TracingProcessor surface — on_trace_start, on_trace_end, on_span_start, on_span_end, shutdown, force_flush — and registers through set_trace_processors(), or add_trace_processor() when the SDK's own exporter is to be kept alongside it.

It exports bounded, metadata-only spans, and only the three types its reader consumes:

span fields kept
AgentSpanData name, handoffs, tools, output_type
HandoffSpanData from_agent, to_agent
GuardrailSpanData name, triggered

Everything else is dropped, including every other span type. Raw prompts, model output, tool arguments, tool results, mcp_data, CustomSpanData payloads, transcription and speech audio, and SpanError.data never reach the file — an allow-list rather than a deny-list, so a field a future SDK version adds stays out without a code change. ResponseSpanData and GenerationSpanData are dropped for a second reason as well: OrcaReplay records model traffic at a proxy and already holds those exchanges byte for byte, so a second copy would be a lossier duplicate of the same conversation.

What the tracing data is for: OrcaReplay records a run and replays it offline, and the three span types above are the part of a run a proxy cannot reconstruct. A handoff reaches the wire as a transfer_to_<agent> function tool, which names the destination and never the source; a guardrail that passes need make no request at all. Verified against openai-agents 0.20.0 and 0.22.2.

The linked page is the integration's own README: install, the interface it implements, what it writes, and how to turn it off.

Test plan

Docs-only, +1/-0 in docs/tracing.md. No code paths are touched, and the entry follows the existing format and position of the list.

The link target was checked after the package was published: pip install orcareplay-openai-agents on a clean interpreter, then a two-agent run with a handoff and a guardrail, which produced agent.start ×2, agent.handoff and agent.guardrail through the processor — on 0.22.2, two minor versions past the one it was written against.

I did not run .agents/skills/code-change-verification/scripts/run.sh: it drives the repository's make targets and needs the full uv dev environment, which is unrelated to a one-line markdown addition. Happy to run it if you would rather I did.

Issue number

n/a

Checks

  • I've added new tests, if relevant — docs-only
  • I've run .agents/skills/code-change-verification/scripts/run.sh — see Test plan
  • I've confirmed all verification steps pass — for the change made: the diff is one markdown line and the linked page resolves
  • If using Codex, I've run /review before submitting this PR — not using Codex

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant