From 70b4aa4e927d7428d76a95dad53036cf7d44d888 Mon Sep 17 00:00:00 2001 From: Mauricio Barragan Date: Thu, 16 Jul 2026 13:07:13 -0600 Subject: [PATCH] chore(openspec): archive gate-sentry-spans and sync observability spec Moves the completed change to openspec/changes/archive/ and creates the canonical openspec/specs/observability/spec.md. Co-authored-by: Cursor --- .../.openspec.yaml | 0 .../2026-07-16-gate-sentry-spans}/design.md | 0 .../2026-07-16-gate-sentry-spans}/proposal.md | 0 .../specs/observability/spec.md | 0 .../2026-07-16-gate-sentry-spans}/tasks.md | 0 openspec/specs/observability/spec.md | 47 +++++++++++++++++++ 6 files changed, 47 insertions(+) rename openspec/changes/{gate-sentry-spans => archive/2026-07-16-gate-sentry-spans}/.openspec.yaml (100%) rename openspec/changes/{gate-sentry-spans => archive/2026-07-16-gate-sentry-spans}/design.md (100%) rename openspec/changes/{gate-sentry-spans => archive/2026-07-16-gate-sentry-spans}/proposal.md (100%) rename openspec/changes/{gate-sentry-spans => archive/2026-07-16-gate-sentry-spans}/specs/observability/spec.md (100%) rename openspec/changes/{gate-sentry-spans => archive/2026-07-16-gate-sentry-spans}/tasks.md (100%) create mode 100644 openspec/specs/observability/spec.md diff --git a/openspec/changes/gate-sentry-spans/.openspec.yaml b/openspec/changes/archive/2026-07-16-gate-sentry-spans/.openspec.yaml similarity index 100% rename from openspec/changes/gate-sentry-spans/.openspec.yaml rename to openspec/changes/archive/2026-07-16-gate-sentry-spans/.openspec.yaml diff --git a/openspec/changes/gate-sentry-spans/design.md b/openspec/changes/archive/2026-07-16-gate-sentry-spans/design.md similarity index 100% rename from openspec/changes/gate-sentry-spans/design.md rename to openspec/changes/archive/2026-07-16-gate-sentry-spans/design.md diff --git a/openspec/changes/gate-sentry-spans/proposal.md b/openspec/changes/archive/2026-07-16-gate-sentry-spans/proposal.md similarity index 100% rename from openspec/changes/gate-sentry-spans/proposal.md rename to openspec/changes/archive/2026-07-16-gate-sentry-spans/proposal.md diff --git a/openspec/changes/gate-sentry-spans/specs/observability/spec.md b/openspec/changes/archive/2026-07-16-gate-sentry-spans/specs/observability/spec.md similarity index 100% rename from openspec/changes/gate-sentry-spans/specs/observability/spec.md rename to openspec/changes/archive/2026-07-16-gate-sentry-spans/specs/observability/spec.md diff --git a/openspec/changes/gate-sentry-spans/tasks.md b/openspec/changes/archive/2026-07-16-gate-sentry-spans/tasks.md similarity index 100% rename from openspec/changes/gate-sentry-spans/tasks.md rename to openspec/changes/archive/2026-07-16-gate-sentry-spans/tasks.md diff --git a/openspec/specs/observability/spec.md b/openspec/specs/observability/spec.md new file mode 100644 index 0000000..ea21cdd --- /dev/null +++ b/openspec/specs/observability/spec.md @@ -0,0 +1,47 @@ +# observability Specification + +## Purpose +TBD - created by archiving change gate-sentry-spans. Update Purpose after archive. +## Requirements +### Requirement: Error monitoring is always active + +The system SHALL report runtime errors to Sentry whenever `SENTRY_DSN` is configured, independent of any tracing configuration. This includes REST, WebSocket feed, and SSE errors captured via `Sentry.captureException`, plus process-level `unhandledRejection` and `uncaughtException` handlers. + +#### Scenario: Error captured with DSN set + +- **WHEN** `SENTRY_DSN` is set and a handled error occurs on the WebSocket, REST, or SSE path +- **THEN** the error is sent to Sentry as an error event + +#### Scenario: No DSN configured + +- **WHEN** `SENTRY_DSN` is empty or unset +- **THEN** Sentry is not initialized and no events are sent, and the application continues running normally + +### Requirement: Tracing spans are gated by an environment flag + +The system SHALL only create and export OpenTelemetry spans when the `SENTRY_TRACING` environment variable is enabled AND `SENTRY_DSN` is set. The flag SHALL default to disabled so that continuous 24/7 operation emits zero spans by default. + +#### Scenario: Tracing disabled by default + +- **WHEN** `SENTRY_TRACING` is unset or falsy (default) +- **THEN** the tracer is a no-op, no spans are created on the hot path, and no spans are exported to Sentry + +#### Scenario: Tracing enabled with DSN + +- **WHEN** `SENTRY_TRACING` is truthy and `SENTRY_DSN` is set +- **THEN** hot-path spans (`ws.message`, `orderbook.process`, `arbitrage.evaluate`, `sse.broadcast`) are created and exported to Sentry, and `tracesSampleRate` is applied + +#### Scenario: Tracing enabled without DSN + +- **WHEN** `SENTRY_TRACING` is truthy but `SENTRY_DSN` is empty or unset +- **THEN** the tracer is a no-op and no spans are exported, since export requires a DSN + +### Requirement: Error capture is preserved when tracing is disabled + +The system SHALL continue to report exceptions thrown inside hot-path work wrappers to Sentry even when tracing is disabled, so disabling spans never reduces error visibility. + +#### Scenario: Exception in hot-path wrapper with tracing off + +- **WHEN** `SENTRY_TRACING` is disabled and code wrapped by the hot-path span helper throws +- **THEN** the exception is still captured and reported to Sentry (as an error), and re-thrown to preserve existing control flow +