Error monitoring

Sentry integration

Ahena works with your Sentry organization: it checks the project your app reports to is actually receiving errors, has an active client key and an issue alert for production, and creates them after you approve. Your app sends events to Sentry directly. Ahena isn't in the path.

BetaFull Sentry docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at Sentry.

The token's scopes, read from Sentry, and the organization's data region (US or EU), so calls go to us.sentry.io or de.sentry.io.
Projects with their platform and status, and the environments Sentry has seen.
Client keys with their public DSN only: never the key secret or the legacy secret DSN.
Recent error events from production, the latest releases, issue alerts and data scrubbing.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Create the project for a team	CONFIRMATION_REQUIRED	Sentry doesn't charge per project; the events it receives count against your quota, shown as a cost notice.
Create a client key	CONFIRMATION_REQUIRED	Only when no key is active. The public DSN is stored as `SENTRY_DSN`.
Create the production issue alert	CONFIRMATION_REQUIRED	New, regressed and reappeared issues, emailed to suggested assignees.

Refused outright:

Deleting, disabling or editing projects, client keys or alerts.
Changing data scrubbing or any other security and privacy setting.

Generated code: src/ahena/monitoring/index.ts (initMonitoring, monitoring.captureException, monitoring.flush, monitoring.raw) over @sentry/node, reading SENTRY_DSN, and .env.example.sentry. For Next.js and browser apps, use Sentry's wizard.

How Ahena verifies

After every write, Ahena reads Sentry back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

Every create re-reads first and only creates what's absent, following Sentry's Link-header cursors to the end, then Ahena re-plans: the change is verified when the second plan is empty.

If a request may have reached Sentry but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the Sentry docs.

Check	What it means
`sentry.token`	The token works and has the scopes Ahena needs; a CI-only organization token is explained.
`sentry.project`	The project exists and is active, with a fix to create it when a team is declared.
`sentry.client_key`	An active client key (DSN) exists.
`sentry.events.production`	Sentry has received error events from production recently.
`sentry.alert.production`	An enabled issue alert covers production.
`sentry.data_scrubbing`	Server-side data scrubbing is on (reported, never changed).

More on findings, health and continuous checks: Doctor.

Approvals

Sentry changes here are classified CONFIRMATION_REQUIRED. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Initialise the SDK in every deployment with SENTRY_DSN and the right environment.
Turn on Data Scrubber in Project Settings → Security & Privacy if Doctor reports it off.
Create releases from CI with an organization auth token.

Credentials and permissions

Name	Secret	Notes
`SENTRY_AUTH_TOKEN`	Yes	An internal integration token. Organization auth tokens (`sntrys_…`) only carry `org:ci` and can't read projects.
`SENTRY_ORG`	No	The organization slug, from `https://<slug>.sentry.io`.
`SENTRY_PROJECT`	No	The project slug; Ahena lists your projects when you connect.
`SENTRY_DSN`	Yes	The public DSN, stored by Ahena when it creates a project or key. Public by design; kept with your secrets because Ahena has no plain environment values.

Least privilege

Grant the internal integration Organization: Read, Project: Read & Write and Alerts: Read & Write. Read-only use needs only the Read permissions.
Ahena reads the token's scopes from Sentry when connecting and reports each as granted, missing or unknown. That endpoint is undocumented, so its answer is advisory: any error makes every scope unknown, and connections and Doctor results are decided by documented calls.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

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

Connect with an internal integration token.

```
ahena doctor -e production
```
Check events, the DSN, environments, the production alert and data scrubbing.
```
ahena plan -e production
```
See the project, client key and alert changes.
```
ahena apply -e production
```
Approve and apply; the public DSN is stored as SENTRY_DSN.
```
ahena generate sentry -e production
```
Write the @sentry/node adapter.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How Sentry is tested

Sentry is tested against a simulated version of its API: real paths and hosts, Link-header cursor pagination, 401s, 403s for missing scopes, 500s and data-region routing.
It hasn't been run against the real Sentry API yet. The token-scope endpoint is unpublished, and the alert payload follows the new Monitors & Alerts reference, so both still need a real run.
The generated adapter is typechecked against @sentry/node 11, not executed.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

Self-hosted Sentry isn't supported.
Only one issue alert per environment is managed; metric alerts, uptime and cron monitors, and Slack or PagerDuty routing are out of scope.
Releases and source maps are read, not created.
A quiet, healthy app also shows zero events.

Disconnecting

ahena disconnect sentry removes the stored token; revoke it on your internal integration in Sentry. Projects, keys, alerts and events are untouched.