docs(tracing): add Long-running workers section with flush_traces() examples#2834
docs(tracing): add Long-running workers section with flush_traces() examples#2834nanookclaw wants to merge 1 commit intoopenai:mainfrom
Conversation
…xamples In long-running worker processes (Celery, FastAPI background tasks, RQ, Dramatiq), traces buffered by BatchTraceProcessor may not be exported before the next task begins, because the process never exits to trigger shutdown flushing. Documents flush_traces() pattern with Celery and FastAPI examples. Explains the silent data loss scenario and references openai#2135 for context. Closes openai#2135
github-actions
bot
added
the
documentation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 314b766b05
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| Use [`flush_traces()`][agents.flush_traces] after each task completes to ensure all buffered spans | ||
| are exported: | ||
|
|
||
| ```python | ||
| from agents import Agent, Runner, trace, flush_traces |
There was a problem hiding this comment.
This new section tells users to call flush_traces() and links to [agents.flush_traces], but that public symbol is not defined/exported in the current SDK (it is absent from both src/agents/tracing/__init__.py and src/agents/__init__.py). In this state, users copying the snippet will hit an ImportError, and the reference link target is unresolved during docs generation, so the docs now prescribe a non-existent API.
Useful? React with 👍 / 👎.
|
As mentioned at Codex reviews, the utility does not exist in this SDK. We may add something similar in the future. In the case, we'll update the documentation as well. |
2 participants
Summary
In long-running worker processes (Celery, FastAPI background tasks, RQ, Dramatiq), traces buffered by
BatchTraceProcessorare silently dropped when the worker picks up the next task — the process never exits to trigger shutdown flushing, so buffered spans are never exported.This PR documents the
flush_traces()pattern with concrete examples for the two most common worker runtimes (Celery and FastAPI background tasks), explains why traces are dropped in worker environments, and points to #2135 for context.Changes
docs/tracing.md: New Long-running workers section inserted before Ecosystem integrations, covering:flush_traces()pattern with Celery exampleflush_traces()pattern with FastAPI background task exampleRelationship to open PRs
PR #2735 adds the
flush_traces()public API. This PR documents it. The two are complementary — users who discover the worker issue via #2135 will find the solution pattern in the docs.Checks
agents.flush_traces,agents.trace,agents.Runner)