Skip to content

CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.

docs(tracing): document flush="background" and update 0.13.1 status

xf gong4125c29f3bb6
diff --git a/website/docs/guides/tracing/otlp.md b/website/docs/guides/tracing/otlp.md
index 0b3d352..f3245c3 100644
--- a/website/docs/guides/tracing/otlp.md
+++ b/website/docs/guides/tracing/otlp.md
@@ -173,3 +173,29 @@ If even that gets missed — say a script raises before reaching `finally` —
that sync-flushes buffered spans through `BatchSpanProcessor`. Doesn't run
on `SIGKILL` / `os._exit`; for guaranteed delivery there, use
`SimpleSpanProcessor` (sync export per span).
+
+### Background flush on serving paths
+
+On request-handling paths — FastAPI endpoints, gRPC handlers, any code where
+a caller is waiting on the `async with` block — awaiting the OTLP flush before
+returning ties your p99 to the slowest exporter. Use the standalone `trace()`
+helper with `flush="background"` instead:
+
+```python
+from cubepi.tracing import trace
+
+async def chat(req: ChatRequest):
+ async with trace(tracer, agent, flush="background"):
+ reply = await agent.prompt(req.message)
+ # Block exits immediately — span export runs as a supervised background
+ # task, decoupled from this response.
+ return {"reply": reply}
+```
+
+Both `force_flush` and the underlying `BatchSpanProcessor` export run in a
+worker thread (off the event loop), so a slow or backlogged collector can't
+stall a user-visible response. The tracer keeps a strong reference to each
+in-flight flush task so it can't be garbage-collected mid-export; `await
+tracer.shutdown()` settles any still-pending flushes before closing exporters,
+so no spans are lost on clean shutdown.
diff --git a/website/docs/intro.mdx b/website/docs/intro.mdx
index dca8cb7..4183c56 100644
--- a/website/docs/intro.mdx
+++ b/website/docs/intro.mdx
@@ -75,7 +75,9 @@ version picker, top-right](pathname:///)). CubePi 0.13 adds
reasoning capability primitives and controls across all providers,
run-scoped compaction with real-token triggering, tool-batch fault
isolation that preserves all checkpoint state, and durable parallel
-HITL approval replay.
+HITL approval replay. 0.13.1 patches the tracing flush path: `force_flush`
+now runs off the event loop, and `trace()` gains a `flush="background"` mode
+for serving paths where span export must not gate a user-visible response.
Source, issues, and discussion live on
[GitHub](https://github.com/cubeplexai/cubepi).
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tracing/otlp.md b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tracing/otlp.md
index e186642..c0172ab 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tracing/otlp.md
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/guides/tracing/otlp.md
@@ -163,3 +163,26 @@ finally:
`Tracer(atexit_flush=True)`(默认)会注册进程退出处理程序,通过
`BatchSpanProcessor` 同步 flush 缓冲 span。`SIGKILL` / `os._exit` 时不运行;
如需保证必达,请使用 `SimpleSpanProcessor`(每个 span 同步导出)。
+
+### 服务路径的后台 flush
+
+在请求处理路径上——FastAPI 端点、gRPC handler、任何调用方在等待 `async with`
+块结果的代码——等待 OTLP flush 完成才返回会让你的 p99 被最慢的 exporter 拖累。
+改用独立的 `trace()` 辅助函数并传入 `flush="background"`:
+
+```python
+from cubepi.tracing import trace
+
+async def chat(req: ChatRequest):
+ async with trace(tracer, agent, flush="background"):
+ reply = await agent.prompt(req.message)
+ # 块立即退出——span 导出作为受监管的后台任务运行,与本次响应解耦。
+ return {"reply": reply}
+```
+
+`force_flush` 和底层 `BatchSpanProcessor` 的导出均在 worker 线程中运行(脱离
+event loop),因此即使 collector 缓慢或积压,也不会阻塞用户可见的响应。
+Tracer 持有每个进行中 flush 任务的强引用,防止其在导出过程中被 GC;
+`await tracer.shutdown()` 会在关闭 exporter 前等待所有未完成的 flush,
+确保 span 不丢失。
diff --git a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
index 02e5ecd..fff33b6 100644
--- a/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
+++ b/website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/intro.mdx
@@ -70,7 +70,9 @@ pip install cubepi
最新已发布版本是 v<PackageVersion />([从右上角版本选择器切换](pathname:///))。
CubePi 0.13 新增所有 provider 的推理能力原语和控制、运行内作用域的
压缩和真实令牌触发、工具批处理故障隔离保留所有检查点状态、以及
-耐用的并行 HITL 批准重放。
+耐用的并行 HITL 批准重放。0.13.1 修复了 tracing flush 路径:`force_flush`
+现在脱离 event loop 运行,`trace()` 新增 `flush="background"` 模式,
+适用于不能让 span 导出阻塞用户响应的服务路径。
源代码、Issue 和讨论都在
[GitHub](https://github.com/cubeplexai/cubepi)。