Skip to content

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.
  • sendDefaultPii is 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 beforeSend does 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:

  1. 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 with environment:staging, correct release and readable stack. Remove the test before producing the next build.
  2. 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.
  3. Inspect event JSON for sensitive data, including a native test crash on a disposable staging install. Confirm native symbols/source maps resolve.
  4. 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.