Skip to content

feat(observability): add bounded source coordinates to failure diagnostics - #74

Open
iperev wants to merge 1 commit into
refactor/remove-unused-publisherfrom
feat/private-diagnostic-coordinates
Open

iperev wants to merge 1 commit into
refactor/remove-unused-publisherfrom
feat/private-diagnostic-coordinates

Conversation

@iperev

@iperev iperev commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

Stacked PR 19 — base: #73 (refactor/remove-unused-publisher). Do not merge yet. Review only the top commit.

Context

CI-066 asks for useful private failure diagnostics that still exclude messages, arguments, locals, secrets and raw provider data. This implements the provisional owner decision (2026-10-11), CI-066 Q9(a).

What changed

  • unexpected_failure adds sourceModule, sourceQualname and sourceLine. These name the innermost first-party frame and are null when there is none.
  • It adds failureFingerprint: 16 hex characters of SHA-256 over the stage, the exception class, and at most eight innermost first-party coordinates, hashed in full. The emitted coordinates are cut to 256 characters.
  • Diagnostic failures stay inside the diagnostic code. If the exception object raises while being read, or supplies a fake traceback, the record falls back to the class-only form with a null fingerprint and null coordinates. The logger's failure counter is incremented, and the HTTP 500 response and the planning fallback are unchanged. Cancellation still propagates.
  • observability.md, recoverable-service-boundaries, REQ-CI-RUNTIME-034 and the CI-066 ROADMAP row are updated.

Expected result

  • Same-class failures at different first-party sites, stages or same-named classes get distinct fingerprints, barring a 64-bit truncated-hash collision.
  • Records contain no failure data.
  • The diagnostic code can no longer change the caller's outcome.

Non-claims

  • The tests have not run locally; they run only in native CI.
  • There is no per-fingerprint rate limiting; showing there is no log storm under load is CI-069's job.
  • A fingerprint is a grouping hint, not a unique identity.
  • This does not prove behaviour in a sourceless or relocated-bytecode deployment.
  • CI-066 is not closed.

Provisional decisions: provisional owner decision (2026-10-11), CI-066 Q9(a).

Independent review: gpt-6-astra (xhigh); findings addressed or rejected with reasons in the single commit. Provisional owner decisions (2026-10-11) are labelled in the changed documents.

…stics

unexpected_failure records now carry the innermost first-party frame's
module, code qualname and line (sourceModule/sourceQualname/sourceLine,
null when no ci_coordinator source frame exists) and a 16-hex
failureFingerprint: truncated SHA-256 over the admitted stage, the
exception class module and qualname, and at most eight innermost
untruncated first-party coordinates. The module is derived as text from
the code filename relative to the loaded package directory; frame globals
are a reserved dynamic-import authority and are not read. Messages,
arguments, notes, locals, file paths and provider data stay excluded;
emission stays one record per failure, and no metric label is added.

The projection is contained inside the diagnostic owner: if the exception
object raises an Exception while its class name, traceback or class
identity is read, or supplies a non-interpreter traceback, the record
degrades to the class-only form (null fingerprint and coordinates), the
logger failure counter is incremented, and the caller's redacted outcome
is unchanged. Cancellation still propagates. Emitted coordinates are
truncated to 256 characters after hashing, so prefix-sharing modules keep
distinct fingerprints.

Requirement impact: REQ-CI-RUNTIME-034 invariant extended for build
identity, source coordinates, the fingerprint and degraded projection.
Provisional owner decision (2026-10-11): CI-066 Q9(a). Per-fingerprint
rate limiting is not implemented; log-storm absence under load remains a
CI-069 measurement.
@iperev
iperev force-pushed the feat/private-diagnostic-coordinates branch from 8d40033 to 339a0fa Compare October 12, 2026 09:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant