Sentry

Overview

Ahena checks that your app's Sentry project is set up and actually receiving errors: the organization and its data region, the project, its client keys (DSN), the environments Sentry has seen, an issue alert for production, releases and data scrubbing. It can create the project, a client key and a production issue alert after you approve them, and generates a small @sentry/node adapter. Your app sends events to Sentry directly. Ahena is never in the path.

Package: @ahena/provider-sentry · Category: monitoring · API: Sentry web API /api/0/ on sentry.io, us.sentry.io and de.sentry.io Capabilities: error-monitoring, projects, client-keys, environments, alerts, releases, data-scrubbing

Maturity: verified against a fake of the API; not yet verified against the real service.

Self-hosted Sentry is out of scope: Ahena only calls sentry.io and its two data-storage regions.

Connection

SENTRY_AUTH_TOKEN=… ahena connect sentry -e production --set SENTRY_ORG=leo-labs --set SENTRY_PROJECT=leo-web

Organization auth tokens (sntrys_…) aren't enough. Sentry gives them a fixed org:ci scope for releases and source maps; they can't read projects, client keys or alerts. Ahena detects one at connect and asks for an internal integration token instead. Keep the organization token for CI.

Data region. Ahena reads the organization from sentry.io, takes its region URL (links.regionUrl) and sends every organization-scoped call to that region (us.sentry.io for US, de.sentry.io for EU), as Sentry's data-residency docs ask. Any other region URL is refused.

Permissions

permissionCheck: "checked". When connecting, Ahena reads the token's scopes from Sentry's API index (GET https://sentry.io/api/0/, the call sentry-cli info makes) and reports each permission as granted, missing or unknown. That endpoint isn't in Sentry's published reference; if it stops reporting scopes, every permission shows as :unknown, never as granted.

These scopes are advisory, never a decision. Because the endpoint is undocumented, any error or unexpected answer from it makes every permission :unknown, and its answer alone never refuses a connection or fails Doctor. Whether Ahena can work is decided by documented calls: the organization read when connecting (401 = token rejected, 403 = it can't read the organization; a token Sentry reports as CI-only is named as such), and each Doctor check's own call (a 403 names the scope it needs). Scope-based findings are at most a WARNING. Sentry's reference lists org:read among the scopes accepted for creating an alert, so a token with org:read and no alerts:write is reported as alerts:write:unknown. Ahena never needs org:write, project:admin, member:* or event:write.

Capabilities

The public DSN is not a secret: Sentry designs it to ship in browser code. Ahena never reads a key's secret field, the legacy secret DSN, or the project's options (which hold a security token); responses are parsed through allowlists. ahena lock records the project's status, platform and scrubbing settings, client key ids (not secrets) and alert names, environments and enabled state for drift.

Configure

monitoring: {
  provider: "sentry",
  organization: "leo-labs",              // or SENTRY_ORG on the connection
  project: "leo-web",                    // or SENTRY_PROJECT
  team: "leo",                           // only needed to create the project
  platform: "javascript-nextjs",         // optional; defaults from `framework`
  environments: ["production", "staging"],
  environment: { production: "production", staging: "staging" },  // Sentry name per Ahena environment (default: the slug)
  alerts: { production: true },          // ensure an issue alert (default: production only)
  noEventsDays: 7,                       // Doctor warns after this many days without events
},

Every value may also be keyed by environment slug.

Why not BILLABLE: creating a project, key or alert costs nothing in Sentry. Cost comes from event volume, which the app generates, not the change. The notice says so before approval.

SENTRY_DSN: Ahena has no non-secret environment values, only encrypted secrets, so the public DSN is returned through the apply result and stored as the secret SENTRY_DSN. It isn't sensitive; it's stored there so ahena env reveal and deploy tooling can read it from one place. For an existing project, copy it from ahena inspect sentry and run ahena env set <env> SENTRY_DSN.

Every create re-reads first and only creates what's absent, so retrying a plan never makes a second project, key or alert. After apply, a second plan with the same configuration is empty once Sentry shows the change (VERIFIED).

Refused: deleting, disabling or editing projects, client keys or alerts; rotating keys; changing data scrubbing, IP scrubbing, sensitive fields or any other Security & Privacy setting. Desired keys such as deleteProject, deleteKey or dataScrubber are rejected with an explanation.

Generate

ahena generate sentry:

• src/ahena/monitoring/index.ts: initMonitoring() starts @sentry/node from SENTRY_DSN (does nothing when it's unset), with environment and release from SENTRY_ENVIRONMENT / SENTRY_RELEASE, tracing off, and reduced data collection (no automatic user fields, cookies or request bodies). monitoring.captureException, monitoring.flush, monitoring.raw.
• .env.example.sentry

Add @sentry/node to your app. The generated code is typechecked against @sentry/node 11 in Ahena's tests. For Next.js, browser apps and source maps use Sentry's own wizard (npx @sentry/wizard@latest -i nextjs): it sets up client, server and edge configs and the build plugin, which a small generated file shouldn't try to replace.

Limitations

• Self-hosted Sentry isn't supported.
• Ahena never deletes projects, client keys or alerts, and never changes security, privacy or data-scrubbing settings.
• Only an issue alert for one environment is managed; metric alerts, uptime and cron monitors, integrations (Slack, PagerDuty) and alert routing beyond email to suggested assignees are out of scope.
• If Sentry hasn't created an error monitor for the project, Ahena can't connect an issue alert to it and says so (create the alert in Sentry instead).
• A project's platform isn't changed; a mismatch with your framework is reported only.
• Releases, source maps and deploys are read, not created: do that in CI with an organization token.
• The "no events" check counts error events only. A quiet, healthy app also shows zero.
• Token scopes come from an unpublished (but long-standing) endpoint; if it changes, permissions show as unknown.
• Personal tokens are bound to a person; prefer an internal integration.

Manual steps

1. Create an internal integration (below) and connect with its token.
2. Initialise the SDK in every deployment with SENTRY_DSN and the right environment.
3. Turn on Data Scrubber in Project Settings → Security & Privacy if Doctor reports it off.
4. Create releases from CI with an organization auth token (sentry-cli or a bundler plugin).

Doctor checks

Set up step by step

1. Create the credential. In Sentry: Settings → Developer Settings → Create New Integration → Internal Integration. Name it "Ahena", save, and copy the token it shows.

2. Grant the minimum permissions on that integration: Organization: Read; Project: Read & Write; Alerts: Read & Write. Read-only use (inspect and Doctor) needs only Organization: Read, Project: Read and Alerts: Read.

3. Connect:

   SENTRY_AUTH_TOKEN=… ahena connect sentry -e production --set SENTRY_ORG=… --set SENTRY_PROJECT=…

4. Verify the connection: ahena inspect sentry -e production shows the organization and its region, projects, environments, client keys (public DSN), releases and alerts.

5. Run Doctor: ahena doctor -e production.

6. Plan: add monitoring to ahena.config.ts, then ahena plan -e production (or ahena configure sentry -e production for this provider only).

7. Apply an allowed change: ahena apply -e production (or answer yes in ahena configure sentry). Creating the production alert is a typical first change.

8. Verify: Ahena re-plans after applying; the change is VERIFIED when the second plan is empty. ahena doctor -e production should now pass sentry.alert.production.

9. Troubleshooting:

   Symptom	Cause	Fix
   "organization auth token (CI scope only)"	An sntrys_ token	Use an internal integration token.
   "Sentry rejected the auth token"	Token revoked or mistyped	Create a new token on the integration and reconnect.
   "missing org:read" / "needs the project:write scope"	Integration permissions too narrow	Edit the integration's permissions, then reconnect.
   "organization … wasn't found"	Wrong SENTRY_ORG	Use the slug from https://<slug>.sentry.io.
   "isn't a sentry.io data-storage region"	Self-hosted or unknown region	Not supported.
   "Sentry isn't receiving events from production"	SDK not initialised, no DSN, or another environment name	Set SENTRY_DSN and environment, trigger a test error.
   Alert action skipped: "no error monitor"	Sentry hasn't created the project's error monitor	Create the alert in Sentry (Alerts → Create Alert).

10. Disconnect and revoke: ahena disconnect sentry -e production, then in Sentry go to Settings → Developer Settings → your internal integration and revoke the token (or delete the integration).

Disconnect behavior

Removes the connection and the token Ahena stored. Ahena can't revoke an integration token itself: revoke it in Settings → Developer Settings → your internal integration. Projects, client keys, alerts, releases and events are untouched.