CubeLoop — a Pythonic, async-native agent harness core designed for high performance, readability, and production-grade persistence.
Python agent-frameworkagent-harnessagent-runtimeagentic-aiai-agentsai-frameworkanthropicharnessharness-engineeringharness-frameworklanggraphlanggraph-alternativellmmcpopenaipi-agentpi-agent-corepythonpython-agent
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.mdindex 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 runon `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+[email protected]("/chat")+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.mdxindex 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 addsreasoning capability primitives and controls across all providers,run-scoped compaction with real-token triggering, tool-batch faultisolation 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.mdindex 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+[email protected]("/chat")+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.mdxindex 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)。