AIM Store crash and error monitoring¶
Extends the Sentry integration already on main for the Expo mobile app
(@sentry/react-native 8.35.0), Go API and Express website. Existing project
identities, credentials and image-derived release IDs are preserved. Reporting
is disabled in environments with an empty DSN. No application deployment or
Play release is part of this PR.
Free plan and project setup¶
Create an account at Sentry and stay on the free Developer plan. For a new environment, use separate React Native, Go and Node projects. Reuse the existing production projects instead of creating duplicates. Choose your organization's data region during account creation.
The pricing page checked 2026-11-17 lists one user, unlimited projects, 5,000 error events and 30-day lookback for Developer. Treat the error allowance as a shared organization budget, not a per-project budget. Check the account's usage page for its actual quota and dropped events; an error spike can exhaust it. No code or SDK setting selects a billing plan. No paid subscription or pay-as-you-go budget is needed for this integration.
Only errors/crashes are enabled. Tracing, profiling, replay, logs and custom metrics are unused/disabled. Error sampling is 100%; routine HTTP 4xx and successful responses do not generate API events. Existing OpenTelemetry/Tempo configuration is independent and unchanged.
Configuration¶
| Location | Variable | Value |
|---|---|---|
| Mobile, EAS environment | EXPO_PUBLIC_SENTRY_DSN |
React Native project's client DSN |
| Mobile, EAS environment | EXPO_PUBLIC_SENTRY_ENVIRONMENT |
production or staging (existing configuration) |
| Mobile, Expo plugin | organization |
Existing public organization slug in app.json |
| Mobile, Expo plugin | project |
Existing React Native project slug in app.json |
| Mobile, EAS secret | SENTRY_AUTH_TOKEN |
Source-map/debug-symbol upload token |
| API runtime env | SENTRY_DSN |
Go project's client DSN |
| API runtime env | SENTRY_ENVIRONMENT |
Defaults to APP_ENV if blank |
| API runtime env | SENTRY_RELEASE |
Deployed git SHA or immutable image version |
DSNs are public ingestion addresses, not API credentials. Never prefix the
upload token with EXPO_PUBLIC_, put it in app config/extra, or commit it.
For local release builds put overrides in ignored aim-store-app/.env.local.
Use EAS environment variables for builds: production profile uses production;
staging uses preview and retains its staging API URLs and package identity.
See Expo/Sentry setup.
The Metro serializer adds Debug IDs; the Expo plugin installs native build hooks for bundle/source-map and iOS debug-symbol uploads. With no upload token, uploads are explicitly disabled so unconfigured builds still work. With a token, uploads are enabled and failures fail the build. Keep the configured plugin organization/project and check upload logs before releasing. The SDK's automatic native release/build identification is preserved so maps match the installed binary.
Android explicitly declares Sentry's normal ACCESS_NETWORK_STATE permission
for delivery retries; no runtime permission prompt is added. Expo config also
includes Sentry's required-reason Apple privacy manifest entries and unlinked,
non-tracking crash/diagnostic categories. The combined app manifest separately
declares linked identifiers/interactions for optional PostHog analytics. See the
Sentry Apple manifest guide.
These additions do not replace the app's existing account/transaction disclosures.
The backend reads its DSN from its existing runtime environment file
(deploy/.env.production in production, deploy/staging/backend.env in staging).
The compose service already loads that file; no new ports or services are
needed. The generator and backend .env.example include empty optional keys.
Restart/redeploy the API after configuring it; startup logs state
[sentry] error reporting enabled=true. Missing/invalid configuration disables
reporting without preventing the API from starting. Invalid DSNs are never logged.
An empty mobile DSN skips initialization entirely. Reporting is also disabled
in __DEV__. The SDK adds native code: rebuild the app with Expo prebuild/EAS;
Expo Go and a JS-only update cannot install native crash handling. This change
does not enable EAS Update or submit anything to Play.
Captured failures and privacy¶
- Mobile: global JS exceptions, unhandled promise rejections, root Expo Router render errors and native SDK crashes after initialization. Native crash reports may arrive on the next launch. Handled business/API validation errors are not automatically reported as client failures.
- API: request panics, returned errors producing 5xx, and handlers writing 5xx directly. Accounting's error helper preserves the underlying exception and suppresses a duplicate generic report. Other direct 5xx reports have a generic message and the route template. Reports use isolated per-request scopes; delivery is asynchronous and shutdown flushes for up to two seconds.
- Panics still reach Fiber's existing recovery handler. Client responses retain their existing shape. The adapter never copies HTTP bodies, headers, cookies, query parameters or actual route IDs into Sentry. It does not instrument background goroutines, fatal startup exits or arbitrary application log lines.
sendDefaultPiiis false. JS events drop user/request/custom context, tags, breadcrumbs and frame locals. Go events drop user/request/context, arbitrary tags, attachments and frame locals; only method, route template and status tags survive. Both redact common credentials, URLs, email and phone-like values from messages. Redaction is best effort: never include customer data in exception messages or add user/payment context to Sentry.- JS
beforeSenddoes not filter native crash events. Native SDKs keep diagnostic stack/device/OS/build metadata and may include SDK installation identifiers. Screenshots, view hierarchies, automatic session tracking and breadcrumbs are disabled. Keep Sentry server-side data scrubbing enabled, review a native event before release, and document the diagnostic processor, identifiers, region and retention in the public privacy policy/Play Data Safety. IP addresses are observable by Sentry's ingestion service.
Verification and activation checklist¶
Local automated verification needs no account, DSN or network ingestion:
cd aim-store-app
npm run verify
npx expo prebuild --platform android --no-install
cd ../aim-backend
go test -race ./internal/observability ./internal/accounting/apierr ./cmd/api
go test ./...
Go tests use an in-memory transport for panic, returned/caught/direct 5xx,
duplicate suppression and ignored 4xx, alongside the existing privacy and
image-release tests. The Node loopback HTTP test verifies one filtered SDK
envelope and shutdown flush without sending anything to Sentry.
Mobile tests verify that upload credentials stay out of app config and that
unconfigured builds keep uploads disabled. Metro export verifies
SDK/bundler compatibility; they do not prove that a live Sentry project receives events.
The merged-manifest check also identified existing Razorpay NFC and
READ_BASIC_PHONE_STATE permissions. Refresh that payment-SDK disclosure audit
before the next production release; this integration changes no payment SDK code.
After the target environment is configured:
- Build a staging release binary with source-map uploads enabled. Use a
temporary
Sentry.captureException(new Error('AIM Store Sentry setup test'))after initialization (never a permanent startup event). Verify the issue in the mobile project's Issues page withenvironment:staging, correct release and readable stack. Remove the test before producing the next build. - In the staging API only, temporarily exercise a test error and a recovered panic through a private/local test handler. Verify exactly one issue event per request, correct route/status/release, normal 500 response and continued service. Remove the temporary handler. No public crash route is shipped.
- Inspect event JSON for sensitive data, including a native test crash on a disposable staging install. Confirm native symbols/source maps resolve.
- In Sentry's UI, enable the free email issue notification rule and check notification preferences. No alerts or outbound messages are created by this code change. Configure production only after staging verification.
For each release, verify live receipt and readable native crash stacks using that environment's configured projects, DSNs and build upload credentials.