feat(observability): expand self-host Sentry context and monitors

[andriypolanski]

Summary

• Export a documented operational taxonomy from src/selfhost/sentry.ts (SENTRY_OPERATIONAL_TAG_KEYS, SENTRY_OPERATIONAL_SUBSYSTEMS, SENTRY_MONITOR_NAMES) and apply allowlisted tags consistently via applyOperationalTags.
• Tag captureError, structured log forwarding, and cron monitor failures with kind, subsystem, jobType, and related low-cardinality fields so Sentry issues point at the affected subsystem.
• Expand Operations docs with enable-your-own-DSN guidance, context taxonomy, and an alert/runbook table for dead-letter growth, check-run permission gaps, AI exhaustion, relay failures, backup failures, and monitor misses.

Closes #1824

Scope

• SENTRY_DSN unset remains a complete no-op (existing behavior preserved)
• Taxonomy + tag allowlist exported for operators and drift tests
• Monitor coverage unchanged (five wrapped loops already on main)
• Scrubbing tests unchanged — no new sensitive fields tagged
• Website docs for enabling Sentry with an operator-owned DSN

Changed files

File	Change
src/selfhost/sentry.ts	Export taxonomy constants; applyOperationalTags; tag captureError/monitor failures
apps/gittensory-ui/src/routes/docs.self-hosting-operations.tsx	Enable Sentry, taxonomy, alert/runbook sections
test/unit/selfhost-sentry.test.ts	Tag + taxonomy export tests
test/unit/docs-selfhost-sentry-observability.test.ts	Doc/taxonomy drift guard

Validation

git diff --check
npx vitest run test/unit/selfhost-sentry.test.ts test/unit/docs-selfhost-sentry-observability.test.ts
npm run test:coverage -- test/unit/selfhost-sentry.test.ts
npm run docs:drift-check
npm --workspace @jsonbored/gittensory-ui run lint
npm --workspace @jsonbored/gittensory-ui run typecheck
npm run test:ci
npm audit --audit-level=moderate

Safety

• Tag allowlist excludes secrets, bodies, diffs, prompts, and raw installation ids
• No maintainer-owned DSN baked into docs or defaults
• High-cardinality blobs stay in scrubbed contexts, not tags

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.37%. Comparing base (1baaece) to head (563b225).
⚠️ Report is 26 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3752      +/-   ##
==========================================
- Coverage   93.37%   93.37%   -0.01%     
==========================================
  Files         316      316              
  Lines       32296    32292       -4     
  Branches    11841    11838       -3     
==========================================
- Hits        30158    30153       -5     
  Misses       1507     1507              
- Partials      631      632       +1     

Files with missing lines	Coverage Δ
src/selfhost/sentry.ts	99.63% <100.00%> (-0.37%)	⬇️

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-06 07:37:27 UTC}

4 files · 1 AI reviewer · no blockers · readiness 100/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• Touches a guarded path — held for manual review: This PR changes guardrail-protected path(s): src/selfhost/sentry.ts (matched src/selfhost/**).

Review summary
This PR exports a documented Sentry taxonomy (SENTRY_MONITOR_NAMES, SENTRY_OPERATIONAL_SUBSYSTEMS, SENTRY_OPERATIONAL_TAG_KEYS) from src/selfhost/sentry.ts and consolidates tag application into a single applyOperationalTags helper, replacing three near-duplicate ad-hoc tagging blocks in captureError, captureReviewFailure, forwardStructuredLogToSentry, and withSentryMonitor. The refactor is behavior-preserving: installation_id_hash still gets tagged even though tagHashedInstallation now receives the already-scrubbed context, because installation_id_hash is itself in the SENTRY_OPERATIONAL_TAG_KEYS allowlist and gets picked up by the generic loop. Docs are expanded with an enable-Sentry guide, taxonomy reference, and an alert/runbook table, backed by a new drift-guard test that keeps the docs and exported constants in sync; the PAYLOAD_KEY scrub regex is also extended to redact comment_text/comment_body, with a matching regression test.

Nits — 6 non-blocking

• applyOperationalTags (src/selfhost/sentry.ts) is written as a dense one-line function; splitting it into normal multi-line statements would make the repo/repository aliasing and tag loop easier to follow.
• tagHashedInstallation is still called from inside applyOperationalTags even though installation_id_hash is now also covered by the generic SENTRY_OPERATIONAL_TAG_KEYS loop — worth a short comment explaining why both paths remain (e.g. for contexts that skip hashedInstallationContext) so a future reader doesn't assume it's dead code.
• The removed explanatory comment that used to sit above SENTRY_LOG_TAG_KEYS (why only string|number values get tagged) isn't replaced near applyOperationalTags; consider keeping a one-line version now that the taxonomy is a public, documented export.
• docs.self-hosting-operations.tsx uses a placeholder DSN host (o0.ingest.sentry.io) in the example .env block — fine for docs, but worth double-checking the example key format still matches whatever Sentry currently issues.
• Consider a short comment on applyOperationalTags documenting the repo/repository normalization rule, since it's easy to miss that 'repository' is deliberately preserved in the tag output alongside 'repo'.
• Touches a guarded path — held for manual review — A maintainer must review and merge this change.

Signal	Result	Evidence
Code review	✅ No blockers	1 reviewer
Linked issue	✅ Linked	#1824
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	✅ 20/20	Low review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 126 registered-repo PR(s), 76 merged, 5 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	andriypolanski; Gittensor profile; 126 PR(s), 5 issue(s).
Gate result	⚠️ Not blocking	Advisory; not blocking this PR.

Review context

• Author: andriypolanski
• Role context: outside_contributor
• Public audience mode: oss maintainer
• Lane context: Repository registration is not available in the local Gittensory cache.
• Public profile languages: TypeScript, JavaScript, Python, Rust, Cuda, Kotlin, MDX, Scala
• Official Gittensor activity: 126 PR(s), 5 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Keep the PR focused and include validation evidence before maintainer review.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review