[slifty]

This is the first, errors-only stage of #2497. It follows the plan in #2497 (comment).

Sentry stays off unless SENTRY_DSN is set, so local development and the tests are unaffected.

What gets reported:

• requests that errorHandler answers with a 5xx (4xx responses are not reported)
• uncaught exceptions and unhandled promise rejections
• startup failures
• the Graphile Worker runner dying

Notes for review:

• Sentry's own Express capture is off. It reads the status from the error object, and our errors don't carry one, so it would report every 4xx too. errorHandler reports instead.
• Request data is locked down. Sentry SDK v11 collects request bodies, cookies, query strings, IP addresses and local variable values by default. src/instrument.ts turns all of that off and allows only the content-type, content-length and user-agent headers.
• The entrypoint uses node --import. SDK v11 no longer supports --require for loading Sentry before the rest of the app.
• No release tagging yet. Events won't say which build they came from. That's planned for a later PR.

Before merging, each deployment needs SENTRY_DSN and SENTRY_ENVIRONMENT set (see docs/SENTRY.md). The Sentry project doesn't exist yet, so this stays a draft until it does.

🤖 Generated with Claude Code
Claude-Session: 45c591f5-c6a1-4f19-ae57-70e3001990b4

[codecov]

Codecov Report

❌ Patch coverage is 20.00000% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.78%. Comparing base (e2548eb) to head (3e24798).
⚠️ Report is 3 commits behind head on main.

Files with missing lines	Patch %	Lines
src/index.ts	0.00%	6 Missing ⚠️
src/scripts/migrate.ts	0.00%	6 Missing ⚠️
src/instrument.ts	0.00%	3 Missing ⚠️
src/jobQueue.ts	50.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2628      +/-   ##
==========================================
- Coverage   94.03%   93.78%   -0.25%     
==========================================
  Files         348      349       +1     
  Lines        4492     4508      +16     
  Branches      588      588              
==========================================
+ Hits         4224     4228       +4     
- Misses        267      279      +12     
  Partials        1        1              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🔎 A preview deployment of this pull request is available at https://utilities.philanthropydatacommons.org/pdc-service-preview-2628-btkjd/ (and upstream https://pdc-service-preview-2628-btkjd.ondigitalocean.app) assuming this PR is still open. 🔍

[bickelj]

I know this is draft, just noticed it and thought I'd give some preliminary feedback.

[Copilot]

🟡 Changes recommended

Two unresolved critical issues remain: startup failures can leave the process alive without serving, and arbitrary non-Error values may leak sensitive data to Sentry despite the documented privacy guarantee.

2 open issues

• Startup failure leaves resources open without exiting · New
• Unsanitized non-Error values can leak sensitive data · New

What changed in this PR

This pull request adds opt-in Sentry error reporting for HTTP 5xx responses, startup and migration failures, uncaught process errors, and Graphile Worker failures, with privacy-focused request-data restrictions and deployment documentation.

Changes:

• Initializes Sentry for the API and migration entry points.
• Reports server, startup, migration, worker, and process-level failures.
• Adds tests for 4xx/5xx reporting behavior.
• Adds Sentry configuration, dependencies, environment variables, and operational documentation.

The pull request requires changes to ensure startup failures terminate the process, preserve Sentry’s default process-level integrations, and sanitize non-Error values before reporting them.

File	Description
src/​scripts/​migrate.ts	Reports migration failures and flushes Sentry events before shutdown.
src/​middleware/​errorHandler.ts	Reports HTTP 5xx errors while excluding 4xx responses.
src/​middleware/​__tests__/​errorHandler.unit.test.ts	Tests Sentry reporting behavior for server and client errors.
src/​jobQueue.ts	Reports Graphile Worker runner failures.
src/​instrument.ts	Initializes Sentry and restricts collected request data.
src/​index.ts	Initializes Sentry and reports startup failures.
src/​constants/​time.ts	Adds the Sentry flush timeout constant.
package.json	Adds the Sentry Node SDK dependency.
package-lock.json	Locks the Sentry SDK and transitive dependencies.
docs/​SENTRY.md	Documents reporting scope, privacy, environments, and configuration.
docs/​HOSTING.md	Links hosting documentation to Sentry setup guidance.
AGENTS.md	Documents Sentry configuration and initialization files.
.env.example	Adds Sentry-related environment variable examples.
.do/​deploy.template.yaml	Adds Sentry deployment environment variables.

_{Review effort: Lite}

[slifty]

Re codecov: the lines changed are entry level files, and I don't think we necessarily want / need test coverage for those lines.