Skip to content

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

fix(tracing): keep raw errors behind content opt-in

Cuecd821f60b3cf
diff --git a/CHANGELOG.md b/CHANGELOG.md
index c126af6..9e7b9d3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,6 +15,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
turn, chat, and tool spans end with `cubepi.run.outcome="suspended"`; observer
failures cannot hide the terminal event, cancellation still propagates, and
`respond()` opens a distinct correlated activation trace.
+- **Raw provider error details now follow the content-recording opt-in.** With
+ `record_content=False`, traces retain typed error classification and ERROR
+ status but use bounded generic descriptions and omit exception messages and
+ stack traces. `record_content=True` preserves the prior diagnostic detail.
## [0.13.3] - 2026-08-02
diff --git a/cubepi/tracing/recorder.py b/cubepi/tracing/recorder.py
index 2ea5c5d..b9f49a9 100644
--- a/cubepi/tracing/recorder.py
+++ b/cubepi/tracing/recorder.py
@@ -844,7 +844,11 @@ class Recorder:
# "error", mark turn ERROR. Abort path leaves UNSET + sets
# cubepi.aborted on the invoke_agent root.
if stop_reason == "error":
- err_msg = getattr(msg, "error_message", None) or "model error"
+ err_msg = (
+ getattr(msg, "error_message", None) or "model error"
+ if self._record_content
+ else "model error"
+ )
run.turn_span.set_status(Status(StatusCode.ERROR, err_msg[:256]))
run.turn_span.set_attribute(ERROR_TYPE, "cubepi.error")
elif stop_reason == "aborted":
@@ -1267,17 +1271,24 @@ class Recorder:
span.set_attribute(CUBEPI_ABORTED, True)
span.set_attribute(ERROR_TYPE, "cubepi.aborted")
else:
- span.set_status(Status(StatusCode.ERROR, str(exc)[:256]))
+ description = (
+ str(exc)[:256] if self._record_content else "provider error"
+ )
+ span.set_status(Status(StatusCode.ERROR, description))
span.set_attribute(ERROR_TYPE, cubepi_error_type_for(exc))
+ exception_attrs = {"exception.type": type(exc).__name__}
+ if self._record_content:
+ exception_attrs.update(
+ {
+ "exception.message": str(exc),
+ "exception.stacktrace": "".join(
+ traceback.format_exception(exc)
+ ),
+ }
+ )
span.add_event(
name=EVENT_GEN_AI_EXCEPTION,
- attributes={
- "exception.type": type(exc).__name__,
- "exception.message": str(exc),
- "exception.stacktrace": "".join(
- traceback.format_exception(exc)
- ),
- },
+ attributes=exception_attrs,
)
finally:
span.end()
diff --git a/dev/plans/2026-08-04-tracing-hitl-suspension.md b/dev/plans/2026-08-04-tracing-hitl-suspension.md
index b59b62a..8dd88fd 100644
--- a/dev/plans/2026-08-04-tracing-hitl-suspension.md
+++ b/dev/plans/2026-08-04-tracing-hitl-suspension.md
@@ -50,6 +50,8 @@ OpenTelemetry SDK, pytest, Ruff, mypy, uv.
- Move assistant output accumulation to `MessageEndEvent` so suspension before
`TurnEndEvent` still records the partial output.
- Do not change `_close_open_spans()` cancellation semantics.
+- When `record_content=False`, preserve typed ERROR classification while using
+ generic status descriptions and omitting exception messages/stack traces.
## Task 4: Document the lifecycle contract
diff --git a/dev/specs/2026-08-04-tracing-hitl-suspension.md b/dev/specs/2026-08-04-tracing-hitl-suspension.md
index 72ea8e8..5ff148e 100644
--- a/dev/specs/2026-08-04-tracing-hitl-suspension.md
+++ b/dev/specs/2026-08-04-tracing-hitl-suspension.md
@@ -37,6 +37,8 @@ left the old `_RunState` retained in that task's context.
- Remove tool-span and MCP-provider registrations during normal tracing detach.
- Count the assistant tool-call message as partial activation output.
- Keep tracing observational: recorder failures must not affect the agent.
+- Keep raw provider error messages and stack traces behind `record_content=True`;
+ privacy-default traces retain only typed error classification.
## Non-goals
diff --git a/tests/tracing/test_content_recording.py b/tests/tracing/test_content_recording.py
index 0b33a5e..1b67c48 100644
--- a/tests/tracing/test_content_recording.py
+++ b/tests/tracing/test_content_recording.py
@@ -102,6 +102,26 @@ class TestContentDisabled:
f"{span.name} should not carry {forbidden} with record_content=False"
)
+ async def test_error_details_are_private_when_record_content_false(self):
+ secret = "Authorization: Bearer TOPSECRET"
+ agent, provider, exporter, tracer = await _build(record_content=False)
+
+ def explode(*_args):
+ raise RuntimeError(secret)
+
+ provider.append_responses([explode])
+
+ await agent.prompt("private prompt")
+ await agent.wait_for_idle()
+ await tracer.shutdown()
+
+ assert any(span.status.status_code.name == "ERROR" for span in exporter.spans)
+ for span in exporter.spans:
+ assert secret not in (span.status.description or "")
+ assert secret not in repr(dict(span.attributes or {}))
+ for event in span.events:
+ assert secret not in repr(dict(event.attributes or {}))
+
class TestRootContent:
async def test_invoke_agent_records_input_output_system(self):
diff --git a/website/docs/guides/tracing/getting-started.md b/website/docs/guides/tracing/getting-started.md
index 9f977d7..b44a30c 100644
--- a/website/docs/guides/tracing/getting-started.md
+++ b/website/docs/guides/tracing/getting-started.md
@@ -147,6 +147,9 @@ The recorder treats cancellation as a control signal, not a failure:
- A provider raising → chat/turn/root close with **status ERROR**, an
`exception` event on the chat span, and `error.type` derived from the
exception class (`timeout`, `connection_error`, fully-qualified class name, …).
+ With the default `record_content=False`, the status description is generic and
+ the event contains only `exception.type`; raw exception messages and stack
+ traces are included only when content recording is explicitly enabled.
- An MCP `tools/call` returning `isError=true` → CLIENT span closes
ERROR + `error.type=mcp.is_error`.
@@ -182,7 +185,8 @@ Optional, opt-in via `Tracer(record_content=True)`:
`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`,
`gen_ai.tool.definitions`, `gen_ai.tool.call.arguments`,
`gen_ai.tool.call.result`, `cubepi.llm.raw_request`,
-`cubepi.llm.raw_response`. See [Content & Redaction](./content-recording).
+`cubepi.llm.raw_response`, provider exception messages, and provider exception
+stack traces. See [Content & Redaction](./content-recording).
## Multiple agents, one process