refactor: drop span and run-log event catalogs from the observability docs (#21779)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `doc/observability.md` and `doc/run-log-events.md` described every
OpenTelemetry span and every run-log event
> - `rules/data-paths.mdc` told authors to update
`doc/run-log-events.md` for each event, so both files only grew: 2,313
and 1,263 lines
> - Each span and event is already defined next to the code that writes
it, and its name is a literal string that a search finds in one step
> - This pull request removes the per-span and per-event catalogs and
keeps only what code does not say
> - The benefit is two short docs that do not drift from the code, and
no rule that makes them grow again

## Linked Issues or Issue Description

Refs #21670, #21700, and #21743 (the same cleanup for other docs).

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/observability.md`, `doc/run-log-events.md`, and
`rules/data-paths.mdc`

**What's wrong?**

The two docs repeated span names, span attributes, and event payloads
that the code defines. Operator setup started at line 138 of
`doc/observability.md`. The rule required a doc edit for every new
run-log event.

**Suggested fix**

Keep operator setup and the Sentry privacy contract. Point to the code
for span and event definitions. Remove the rule line that requires a doc
entry per event.

## What Changed

- `doc/observability.md` is now 619 lines. It keeps: how to enable
tracing, `service.version` resolution, scope, how to enable Sentry, DSN
delivery, environment attribution, privacy settings, server request
data, the core of "Run failure context", browser data, fail-open
behavior, the default capture set, and operator responsibilities. Kept
text is unchanged except the intro and two sentences noted below.
- Deleted from `doc/observability.md`: budget, Slack receipt, task
detail, and browser tracing notes; controller preparation phases; native
Runner spans; sandbox startup spans; sandbox duplex transport; shared
skill preparation; invocation attribution; and about 500 lines of
per-failure detail in "Run failure context".
- Replaced that per-failure detail with one paragraph. It names the
failures that `unexpected` mode keeps out of Sentry, and says the
remaining diagnostic contexts are defined in `server/src/sentry.ts`.
"Default capture set" now says the same.
- `doc/run-log-events.md` is now 23 lines. It says what the run log is,
where events are defined and appended, and keeps the payload storage
note.
- `rules/data-paths.mdc`: the run-log line now says to define an event
where it is written, not in a doc. The span-allowlist line now says the
allowlist is in the code that opens the span. The review levels and
globs do not change.
- Repointed links in two feature maps, two agent-access map files,
`tests/runner-e2e/SUITES.md`, `doc/runner-api-tools.md`, and the
Telemetry README. Updated the `honeycomb-tracing` skill and one code
comment in `packages/adapter-utils/src/http2-bridge-server.ts`.

## Verification

- A script built the new `doc/observability.md` from line ranges of the
old file and asserts the first line of each range.
- A link check on all changed Markdown files found 0 missing files and 0
missing anchors. The remaining inbound anchors (`#enabling-tracing`,
`#sentry-error-monitoring`) still exist.
- No test reads either doc.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `pnpm verify` was not run. This worktree has no installed
dependencies. The only code change is a comment.

## Risks

- The privacy contract no longer lists each run-failure diagnostic
context field. `server/src/sentry.ts` is now the list. A reviewer of a
Sentry change must read that file.
- No browsable list of span names or run-log event names remains. A
search for the quoted name finds the producer.
- `.greptile/files.json` still scopes `rules/data-paths.mdc` to both
docs. Both files still exist, so it does not change.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Claude Code desktop, with tool
use. Earlier analysis in this session used Claude Fable 5.2.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 authored and GitHub committed 2026-11-15 10:06:05 -06:00
1 parent 531db3c10b
commit 171e70c11d
15 files changed
+80 -2997

No files matched your search

+6 -5
View File
@@ -22,11 +22,12 @@ replaying tasks, changing credentials, or deploying instrumentation.
| What is a page's real-user load time or SLO on a hosted instance? | Browser `page.load` spans in [browser performance tracing](../../../doc/browser-performance-tracing.md) |
| Which CI jobs or test files delay the whole suite? | [CI profiling](references/ci.md) |
| How should a trace be organized so a person can understand it? | Human-readable waterfall guidance below and [trace design](references/trace-design.md) |
| Where should a new span go? | Instrumentation guidance below and [Observability contract](../../../doc/observability.md) |
| Where should a new span go? | Instrumentation guidance below and the code that opens the nearest existing span |
Repository-relative paths and commands assume the checkout root. The maintained
contracts are `doc/observability.md` and `doc/ci-profiling.md`; recheck them and
the owning code when a deployed version differs.
Repository-relative paths and commands assume the checkout root. Span names and
attributes are defined in the code that opens each span; `doc/observability.md`
covers only operator setup and Sentry. `doc/ci-profiling.md` covers CI traces.
Recheck the owning code when a deployed version differs.
Keep the repository's three paths distinct:
@@ -178,7 +179,7 @@ explain one slow scan.
Observability must not retry the operation, replace its return/error, change
authorization/locks, or break execution when the tracer fails. Preserve root
sampling and the explicit endpoint gate even if another library registers an
OTel provider. Update `doc/observability.md` when the trace contract changes.
OTel provider. Update `doc/observability.md` only when operator setup changes.
Run focused tests for endpoint-off behavior, parentage/concurrent-run isolation,
failure handling, and the changed seam. Use real exported evidence to claim that
new spans appear in Honeycomb; a unit-test tracer alone does not prove ingestion.
@@ -2,9 +2,9 @@
Read this when adding, reorganizing, or reviewing a waterfall's hierarchy.
The goal is to understand the work at a glance, then expand the slow phase to
find its cause. Follow the current
[Observability contract](../../../../doc/observability.md) for exact names,
roots, lifecycle boundaries, sampling, and allowed attributes.
find its cause. Follow the code that
opens the nearest existing span for exact names, roots, lifecycle boundaries,
sampling, and allowed attributes.
## Organize by the work being done
+1 -1
View File
@@ -122,7 +122,7 @@ and coverage requirements.
This repo has three separate data paths: Telemetry, Observability, and the run log. See [`rules/data-paths.mdc`](rules/data-paths.mdc) for the full definitions and the review level each path needs.
If your change adds, removes, or modifies emitted telemetry events, update the [Telemetry Data Contract](packages/shared/src/telemetry/README.md) in the same PR. Keep clients emitting raw dimension values and avoid documenting or relying on private delivery details. If your change adds, removes, or modifies an OpenTelemetry span or span attribute, keep the change inside the closed span-attribute allowlist in `packages/adapter-utils/src/acpx-engine/startup-timing.ts`. If your change adds or modifies a run-log event, update `doc/run-log-events.md` in the same PR.
If your change adds, removes, or modifies emitted telemetry events, update the [Telemetry Data Contract](packages/shared/src/telemetry/README.md) in the same PR. Keep clients emitting raw dimension values and avoid documenting or relying on private delivery details. If your change adds, removes, or modifies an OpenTelemetry span or span attribute, keep the change inside the closed span-attribute allowlist in `packages/adapter-utils/src/acpx-engine/startup-timing.ts`. Define a new or changed run-log event where it is written; do not list it in a doc.
### Paperclip Gates Must Pass
+36 -1716
View File
File diff suppressed because it is too large. Load diff
+17 -1256
View File
File diff suppressed because it is too large. Load diff
+1 -1
View File
@@ -343,7 +343,7 @@ idempotent redaction projection. Repeated projection preserves the original
payload digest. Provider recovery uses the same projection to compare saved
completion results with provider history. Changed private bodies still conflict.
Restart preparation preserves the run's admitted REST credential scope, even
when the task mode changes. See [the run-log guide](run-log-events.md) for stored fields.
when the task mode changes. The stored fields are defined where the run-log event is written.
The server-issued REST credential for the bound run is never returned to the model.
Streaming, WebSocket, MCP and authentication
+1 -1
View File
@@ -79,7 +79,7 @@ receipt and inline response policy as newly created webhook secrets.
Task image access requires the company boundary and the task permission;
skill-test and low-trust agents do not need company-wide browsing authority.
Completion replay applies the same idempotent projection to stored and expected
payloads; [the run-log guide](../../doc/run-log-events.md) describes its fields.
payloads; its fields are defined where the [run-log event](../../doc/run-log-events.md) is written.
Sources: [API client](../../server/src/services/native-runtime/runner-api-client.ts),
[catalog](../../server/src/services/native-runtime/runner-api-catalog.ts),
+2 -1
View File
@@ -287,7 +287,8 @@ The native first-text span ends after text is committed for the existing run-eve
reader, including reasoning and completed responses. It exports only the bounded
text kind and timing, with no text content or new agent access.
This adds no agent API, credential access, run-log write, or recovery authority.
See [the tracing contract](../../doc/observability.md#controller-preparation-phases).
See the spans in
[`execution-preparation-timing.ts`](../../server/src/services/execution-preparation-timing.ts).
Live latency verification remains separate from the existing access baseline.
API: `present` — representative operation IDs:
+2 -1
View File
@@ -110,7 +110,8 @@ Eyes should appear after authorized task/comment persistence, independently of
file preparation, subscription and agent startup. Duplicate delivery must keep
one receipt; the final reply must remove only its source message's eyes. Record
live mention-to-reaction timing separately from the PostgreSQL fixture tests and
the `chat.slack.receipt` transport span described in [Observability](../../doc/observability.md).
the `chat.slack.receipt` transport span in
[`receipt-timing.ts`](../../server/src/services/chat-channels/slack/receipt-timing.ts).
During a top-level DM run, verify that the bot adds eyes to the source message
and removes them when the final reply arrives. The pinned Slack SDK encodes a
+2 -1
View File
@@ -44,7 +44,8 @@ For latency diagnosis with an operator OTLP endpoint, search the hashed run ID
without restricting the root span name. Compare workspace preparation with its
`workspace_<step>` intervals. Measure controller readiness separately through
`controller.startup.<phase>`. A recovery pause or deployment drain is not model
execution time. See the [tracing contract](../../doc/observability.md#controller-preparation-phases).
execution time. See the spans in
[`execution-preparation-timing.ts`](../../server/src/services/execution-preparation-timing.ts).
These source-level diagnostics do not establish a live response-time budget.
`task.time_to_first_token` measures accepted ingress through the first committed
text that the task transcript can show, including thinking and completed
@@ -132,9 +132,8 @@ export const HTTP2_BRIDGE_SERVER_OPTIONS: http2.ServerOptions = {
* total, so no combination of concurrent streams, across every route, can
* retain more than this many bytes at once. This value keeps the accepted
* process ceiling at 1,073,741,824 bytes (1 GiB) — the same ceiling
* `doc/observability.md` already accepted before the per-body limit rose to
* 10 MiB — now enforced by this reservation instead of left as an unenforced
* document note. See the per-route budget comment above for the full
* the project already accepted before the per-body limit rose to 10 MiB —
* now enforced by this reservation instead of left as an unenforced note. See the per-route budget comment above for the full
* accounting.
*/
export const HTTP2_BRIDGE_MAX_PROCESS_BODY_BYTES = 1024 * 1024 * 1024;
+2 -3
View File
@@ -126,9 +126,8 @@ This document covers Paperclip Telemetry only. The generated Telemetry
contract covers neither the Observability path nor the run-log path. Two other
data paths document their own contract in their own file:
- [Observability](../../../../doc/observability.md) — the OpenTelemetry trace
path, the sandbox startup trace spans, and the sandbox duplex transport
instrumentation.
- [Observability](../../../../doc/observability.md) — the operator-enabled
OpenTelemetry trace path and Sentry error monitoring.
- [Run-Log Events](../../../../doc/run-log-events.md) — events written to the
local `heartbeat_run_events` table.
+3 -3
View File
@@ -49,10 +49,10 @@ Apply a review level that matches the path:
- **Observability change (lighter review).** The operator endpoint gate stays in
place. The no-operation behaviour stays when no endpoint is set. A privacy
review is not necessary while the change stays inside the closed
span-attribute allowlist.
span-attribute allowlist defined in the code that opens the span.
- **Run-log change (no extra review).** A run-log change needs neither review
level above, because the data stays in the instance database. Update
`doc/run-log-events.md` when an event is added or changed.
level above, because the data stays in the instance database. Define the
event and its payload where it is written; do not list it in a doc.
## Exclusion
+1 -1
View File
@@ -1861,7 +1861,7 @@ Results can include a `startupReuse` entry for each run. The dashboard shows
receipt-derived warmth, the environment/lease, workspace, Runner, provider
process and session decisions, and observed provider launches. Private attempt
evidence includes `snapshots/startup-reuse.json`. See the
[run-log contract](../../doc/run-log-events.md#startup-reuse-evidence) for the
[startup reuse receipt](../../packages/adapter-utils/src/startup-reuse.ts) for the
closed states and reasons. Historical runs without receipts show unknown
values. Provider-session continuity does not establish physical process reuse.
@@ -351,7 +351,7 @@
"packages/shared/src/slack-tools.ts": "c53a75cd3099c6d8dcd1475e755aae589d4c88f6",
"packages/shared/src/subscriptions.ts": "ef70e63395ca967bbc30776b71560e96eb354a75",
"packages/shared/src/summary-slot.test.ts": "5f8e222dea425f0d5bff0adb5c683087bd7cf7fb",
"packages/shared/src/telemetry/README.md": "e792827b9f1e629ccdb66eecaad014cd02e532e8",
"packages/shared/src/telemetry/README.md": "28125b5ab542abc46c4bb6c044636a093f13584f",
"packages/shared/src/telemetry/client-types.test.ts": "3b630edda4972b929ba4decd7457f226eb9cfc5b",
"packages/shared/src/telemetry/client.test.ts": "3ba900cdab5a1ac1dcc1dcea382bb790af32d895",
"packages/shared/src/telemetry/client.ts": "03a10a5550b542487543fbfd4a417e6eb316e11e",