AIM Store monitoring and analytics¶
Components and coverage¶
| Tool | Implemented coverage | Configuration |
|---|---|---|
| Sentry | React Native JS/native crashes, Router errors; Go panics/5xx; Express caught/unhandled errors and 5xx | Separate client DSNs; no tracing, replay, profiling or logs |
| PostHog | Mobile and storefront shopping journeys, after consent | Project 743463, US ingestion; public token in ignored local env files |
| Prometheus | Go/API and Node/payment metrics, CPU, memory, disk, container health | Existing private scrapes, 30-day / 10-GB retention bounds |
| Grafana | Health overview, host/container/API dashboards and corrected application logs | Provisioned JSON; existing unified alert rules |
| Loki + Alloy | Centralized Docker application logs | 14-day retention; common credentials filtered during ingestion |
| Uptime Kuma | Website, website API, Go API, admin, accounts, support and Grafana | Seven persistent HTTP monitors, 60-second intervals, two retries, TLS verification |
The admin monitor uses its public /api/auth/session availability endpoint,
which returns 200 while logged out; the root intentionally responds 307.
All requests are read-only. No test order or payment is created.
Analytics consent and data¶
The SDK is initialized only after the customer opts in. The website has an Analytics preferences control below its footer; mobile has Settings → Usage analytics. Existing customers start with analytics off. Development mobile builds and Vite dev mode also disable capture. Consent survives a restart; withdrawal stops capture and resets SDK identity. Replay, click/touch recording, automatic lifecycle capture, PostHog error tracking, surveys and remote feature flags are disabled. Sentry owns error reporting.
The SDK stores a random identifier locally to recognize repeat visits. Signed-in
customers are identified by their database UUID; names, phone numbers, emails
and profile fields are not sent. Logout resets identity. before_send permits
only these events and approved metadata:
| Event | Trigger |
|---|---|
screen_viewed |
Entry to an approved screen category; paths/IDs/queries are replaced by a fixed category |
cart_item_added |
Cart item count increases |
checkout_started |
Entry to checkout, including its sign-in gate |
order_completed |
Checkout receives a committed backend order; deduplicated in memory by order ID, which is never sent |
$identify |
Consenting customer signs in; UUID only |
Metadata is restricted to surface (web/mobile), environment, fixed screen
name, SDK version and protocol identifiers. Raw URLs, referrers, search terms,
form/OTP data, prices, order IDs and payment fields are dropped. GeoIP enrichment
is disabled on emitted events; the ingestion service still observes network IP.
Analytics data describes opted-in traffic, not all customers or financial totals.
Check the project's retention, data-processing terms and spending limits in its
settings; application code does not select billing plans or enforce cloud quotas.
For an account-data deletion request, the operator must also remove the matching
UUID profile/events using PostHog's privacy controls. SDK identity reset stops
linking future activity; it does not delete historical cloud data. Automated
PostHog erasure is not wired to account deletion by this change.
SDK references: PostHog React Native, React Router declarative mode.
Release configuration¶
| Target | Public variables |
|---|---|
| Mobile / EAS production and preview environments | EXPO_PUBLIC_POSTHOG_PROJECT_TOKEN, EXPO_PUBLIC_POSTHOG_HOST=https://us.i.posthog.com |
| Website build / GitHub repository variables | VITE_POSTHOG_PROJECT_TOKEN, VITE_POSTHOG_HOST=https://us.i.posthog.com |
| Website build | VITE_APP_ENVIRONMENT=production or staging |
Real public values are configured in ignored .env.local files for local
verification. Committed env templates stay empty. The website Dockerfile and
production/staging workflows pass the public values at build time. Configure
the matching EAS/GitHub variables before producing releases; runtime-only env
changes cannot alter a built client bundle. Web CSP permits only the two
PostHog cloud ingestion origins, with no analytics script wildcard.
The Sentry integration already on main is preserved, including its configured
project identities and image-derived release IDs. An empty DSN disables
reporting in an unconfigured environment. The Express service
uses its own Node project with SENTRY_DSN, SENTRY_ENVIRONMENT, SENTRY_RELEASE
in deploy/website.env.production; Go uses the backend env file. Mobile uses
EXPO_PUBLIC_SENTRY_DSN plus private build upload credentials. See
the Sentry runbook. No auth token belongs in a public env
variable. Express reports one event per failed response and preserves the
underlying caught exception, ignores 4xx and flushes during graceful shutdown.
The mobile and website source integrations require their normal release/deploy process. No Play Store submission or application-server deployment is performed by the monitoring-stack rollout. Privacy-policy source and Play/Apple data declarations have been updated alongside the consent controls.
Uptime Kuma and operations¶
See monitoring/README.md for provisioning and the
SSH tunnel. The dashboard is bound to 127.0.0.1:3005, with a persistent volume
and a generated admin credential file of mode 600. Provisioning never resets
an existing account or removes monitors. The requested email recipient is
admin@aimstoreorg.com; Grafana's ops-email contact point routes there.
Resend supplies SMTP at smtp.resend.com:465 with implicit TLS and certificate
verification. The existing workspace has mail.aimstoreorg.com verified, so
the sender is alerts@mail.aimstoreorg.com and the recipient remains
admin@aimstoreorg.com. An initial root-domain sender test was rejected by
Resend; no DNS changes were needed to use the already verified subdomain.
The backend's existing private Resend key is reused entirely on the server;
Grafana reads it from monitoring .env and Kuma's setup script reads Grafana's
running settings in memory. Existing Grafana alert rules remain in place.
See the monitoring README for notification setup, read-only verification,
optional test sending and key rotation.
Both setup test emails were confirmed delivered in Resend's metadata on
17 November 2026. Kuma's named notification is default and attached to all seven
monitors. Read-only verification checks the assignments and matching SMTP
settings; it does not send recurring test messages.
On the VPS:
cd /opt/aim-store/monitoring
bash uptime-kuma/provision.sh
python3 verify-stack.py
The read-only verifier checks eight required Prometheus jobs, six overview
queries, recent application log ingestion, Grafana dashboard loading and Kuma.
Loki's old imported dashboard used a missing job label and unresolved import
datasource; it now uses container and datasource UID loki.
Backups of the prior monitoring compose, Alloy config and logs dashboard are in
monitoring/.backups/observability-20261117T142727Z on the VPS. Dashboard files
reload through Grafana provisioning; Alloy is restarted to apply filtering.
The rollout starts Kuma through compose up -d --no-deps uptime_kuma, so no
application containers are recreated. Keep the new Kuma volume and credential
file if rolling back configuration; do not run compose down -v.
Kuma on this VPS can detect application, DNS and TLS failures while the host runs. A separate external monitor/host is needed to detect a full VPS outage. An existing optional Tempo container was found stopped after an OOM at its 256-MB limit; restoring tracing is outside the six-tool rollout and is not counted as healthy by the verifier.
Verification evidence¶
- Mobile: 915 passing tests, full verification suite, type checking and Android release JS export; iOS prebuild privacy manifest inspected.
- Website: 435 passing tests and production build; Node SDK envelope delivery verified through a loopback HTTP ingestion endpoint without sending test errors to Sentry.
- Browser: opt-in, shopping navigation/cart/checkout and persisted opt-out
exercised against a local production build. PostHog received
screen_viewed,cart_item_addedandcheckout_startedwithenvironment=test. - Sensitive event-property filtering and safe route classification have unit tests. Existing customer data is not used in analytics verification.
- Uptime monitor targets were checked for successful HTTP responses before
provisioning. Live infrastructure is checked by
verify-stack.py. - Disposable isolated log probes verified filtering through Alloy into Loki, including numeric/string credentials with valid JSON preserved. Probes were removed after verification.
- Deployment workflow safety, generated-environment cycle and edge allocation checks passed on an isolated Linux source fixture; the environment-generation check simulated a fresh machine without Docker access.
Native-device analytics and crash receipt need a rebuilt release binary; Metro export verifies bundling only. Existing production Sentry configuration is preserved; no Sentry account or billing plan is changed by this PR.