GlitchTip Monitoring Setup

GlitchTip Monitoring Setup

GlitchTip is Sentry-compatible, so this repo uses the official Sentry SDKs for minimal error monitoring.

Instrumented apps

Browser runtimes

• apps/dashboard — TanStack Start + React + Vite
• apps/marketing — Astro + Vite

Cloudflare/server runtimes

• apps/dashboard — Cloudflare Worker SSR/server functions
• workers/consumer-api — Hono Cloudflare Worker
• workers/ingestion-orchestrator — ingress queue + ORCID sync control plane
• workers/ingestion-process — heavy ORCID/OpenAlex/Crossref processing pipeline
• workers/notification — email and Discord notification delivery
• workers/person-query — people query service
• workers/person-write — people write service
• workers/publication-query — publications query service
• workers/publication-write — publications write service

Inspected but intentionally not instrumented in this minimal rollout

• apps/docs — Starlight docs site, mostly static
• workers/rate-limiter — Durable Object helper
• workers/log-processor — tail/log processor

Packages added

• @sentry/browser
• @sentry/cloudflare

Shared helper

A small shared monitoring utility lives in:

• packages/utils/src/monitoring.ts

It provides:

• captureException(error, context?)
• captureMessage(message, level?, context?)
• safe no-op behavior when no DSN is configured
• basic redaction of sensitive fields before events are sent

Files changed

Shared

• packages/utils/src/monitoring.ts
• packages/utils/src/index.ts

Dashboard app

• apps/dashboard/src/lib/monitoring.ts
• apps/dashboard/src/app/entry-client.tsx
• apps/dashboard/src/app/entry-server.tsx
• apps/dashboard/src/server/functions/info.ts
• apps/dashboard/src/components/feedback/DebugWidget.tsx
• apps/dashboard/src/vite-env.d.ts
• apps/dashboard/.env.example

Public site

• apps/marketing/src/lib/monitoring.ts
• apps/marketing/src/layouts/BaseLayout.astro

Workers

• workers/consumer-api/src/monitoring.ts
• workers/consumer-api/src/index.ts
• workers/consumer-api/shared-env.d.ts
• workers/ingestion-orchestrator/src/monitoring.ts
• workers/ingestion-orchestrator/src/index.ts
• workers/ingestion-orchestrator/shared-env.d.ts
• workers/ingestion-process/src/monitoring.ts
• workers/ingestion-process/src/index.ts
• workers/ingestion-process/shared-env.d.ts
• workers/notification/src/monitoring.ts
• workers/notification/src/index.ts
• workers/notification/shared-env.d.ts

Required env vars

Dashboard browser (Vite client env)

Use the VITE_ prefix:

VITE_SENTRY_DSN=https://<public-key>@errors-monit.legaciti.org/<project-id>
VITE_SENTRY_ENVIRONMENT=production
VITE_SENTRY_RELEASE=2026-04-18+<git-sha>

Public site browser (Astro public env)

Use the PUBLIC_ prefix:

PUBLIC_SENTRY_DSN=https://<public-key>@errors-monit.legaciti.org/<project-id>
PUBLIC_SENTRY_ENVIRONMENT=production
PUBLIC_SENTRY_RELEASE=2026-04-18+<git-sha>

Cloudflare Workers / server runtimes

Use Wrangler secrets or vars, with no public prefix:

SENTRY_DSN=https://<public-key>@errors-monit.legaciti.org/<project-id>
SENTRY_ENVIRONMENT=production
SENTRY_RELEASE=2026-04-18+<git-sha>
SENTRY_TRACES_SAMPLE_RATE=0.05

For monitored workers in this repository, SENTRY_ENVIRONMENT is set in wrangler.jsonc for production, and SENTRY_DSN should be provisioned as a Wrangler secret.

SENTRY_TRACES_SAMPLE_RATE must be a value from 0 to 1.

• Missing/empty value: runtime default by environment
• Invalid value (non-numeric or outside 0..1): forced to 0

Environment defaults used when SENTRY_TRACES_SAMPLE_RATE is omitted:

• development: 1.0
• preview/staging: 0.1
• production: 0.05

Suggested rollout strategy:

1. Preview: 1.0 for short validation windows.
2. Production initial: 0.02 to 0.05.
3. Increase only if event volume and cost are acceptable.

Worker audit and dev setup tooling

Audit all workers for Sentry wiring

node scripts/monitoring/audit-worker-sentry.mjs

This checks all worker folders and reports:

• whether a worker is Sentry-instrumented
• whether SENTRY_ENVIRONMENT is present in its wrangler.jsonc
• whether shared env typings include Sentry fields

Provision GlitchTip dev secrets for all monitored workers

GLITCHTIP_DEV_DSN='https://<key>@<glitchtip-host>/<project-id>' \
node scripts/monitoring/setup-glitchtip-dev.mjs

Optional overrides:

# Per-worker DSN override (example for worker-person-write)
GLITCHTIP_DEV_DSN_WORKER_PERSON_WRITE='https://<key>@<host>/<project-id>'

# Optional knobs
GLITCHTIP_DEV_ENVIRONMENT='development'
GLITCHTIP_DEV_TRACE_RATE='1.0'
CLOUDFLARE_TARGET_ENV='development'

The setup script writes, per monitored worker:

• SENTRY_DSN
• SENTRY_ENVIRONMENT
• SENTRY_TRACES_SAMPLE_RATE

into Wrangler secrets for the selected Cloudflare environment.

Security defaults

• No-op when DSN is missing
• sendDefaultPii: false
• tracing defaults are environment-driven unless overridden by SENTRY_TRACES_SAMPLE_RATE
• request headers, cookies, query strings, and request bodies are stripped before send
• obvious sensitive keys such as authorization, cookie, token, secret, password, and api_key are redacted

How to test

Browser-side test

1. Run the dashboard locally or enable the existing debug widget.
2. Open the debug widget.
3. Click Test Browser Error.
4. Confirm the event appears in GlitchTip.

Server-side test

1. Open the same debug widget in the dashboard.
2. Click Test Server Event.
3. Confirm the server-side event appears in GlitchTip.

The debug test buttons are intended for development or internal/admin debugging only.

Manual verification alternative

If you prefer not to use the debug widget, temporarily add:

throw new Error("GlitchTip manual verification test");

to the relevant browser or worker path, confirm the event arrives, then remove it.