Skip to content

build(selfhost): Sentry source maps, env docs, and Grafana resource-hub link #1469

Description

@JSONbored

Context

The self-host Docker image runs the minified, bundled dist/server.mjs (esbuild via scripts/build-selfhost.mjs). With no source maps, a Sentry stack trace (from the sibling Sentry-wiring issue) points at bundled column offsets and is unreadable. This issue makes stacks readable and documents/links the integration. Depends on the @sentry/node wiring issue being merged (or can land alongside it).

Requirements

  • Emit and ship source maps so both Node runtime logs and Sentry symbolicate against the real source.
  • SENTRY_RELEASE (defaulting to GITTENSORY_VERSION) is the single source of truth tying SDK release to any uploaded maps.
  • Document every env var as opt-in; default behavior with all unset is unchanged.

Deliverables

  • scripts/build-selfhost.mjs: add sourcemap: true to the esbuild config (emit dist/server.mjs.map); keep minify as-is.
  • Dockerfile: add NODE_OPTIONS=--enable-source-maps (or --enable-source-maps in the CMD) so Node rewrites stacks; COPY dist/server.mjs.map into the runtime stage alongside dist/server.mjs.
  • (Optional, gated) a SENTRY_AUTH_TOKEN-gated sentry-cli sourcemaps upload dist/ step keyed on GITTENSORY_VERSION (release MUST equal the SDK release), skipped when the token is absent.
  • .env.example + docs/self-hosting.md: document SENTRY_DSN(/SENTRY_DSN_FILE), SENTRY_ENVIRONMENT (default production), SENTRY_RELEASE (default GITTENSORY_VERSION), SENTRY_TRACES_SAMPLE_RATE (default 0), plus the privacy-scrub note (headers/tokens stripped before send). Note SENTRY_DSN_FILE is handled for free by the existing loadFileSecrets() <NAME>_FILE convention.
  • grafana/dashboards/resource-hub.json: add a links[] entry { "title": "Sentry — errors", "type": "link", "url": "<project-url>", "icon": "bolt", "targetBlank": true, "tooltip": "Crash & error tracking (uncaught, dead-letter jobs, review failures)" } and an 'Error tracking → Sentry' bullet in the Observability text panel, with a one-line operator-edit note for the concrete project URL (or a $sentry_url constant variable so it is edited in one place).

Acceptance criteria

  • npm run build (selfhost) produces dist/server.mjs + dist/server.mjs.map; the runtime image contains both and runs with --enable-source-maps.
  • A thrown error in the running container produces a source-line stack (not bundled offsets).
  • .env.example/docs/self-hosting.md describe all four vars + the scrub note; with everything unset the engine is byte-identical.
  • resource-hub.json remains valid Grafana JSON (loads without provisioning error) and shows the Sentry link + bullet.
  • npm run test:ci green; npm audit --audit-level=moderate clean. No src/** logic change, so no Codecov patch impact expected; if any helper under src/** is touched, cover it to 97% branch.

Parent: #1029

Metadata

Metadata

Assignees

Labels

maintainer-onlyOwner-only work — yields no Gittensor points.

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions