Operations and Rollout

Deployment order

For a coordinated analytics change:

1. Merge the feature branch into dev and deploy Dev App and Auth.
2. Run the complete Dev smoke test in a new browser session.
3. Validate Activity, Replay, environment properties, identity stitching, and privacy.
4. Promote the same commits from dev to stage.
5. Validate the Stage build without expecting a separate Stage analytics dataset.
6. Promote from stage to main.
7. Confirm Production Vercel variables before deploying App and Auth.
8. Run one controlled Production smoke test.
9. Verify Stats, PostHog Activity, and the direct Replay link.
10. Monitor for at least 48 hours after a material instrumentation change.

Use the same commits across branches. Avoid recreating the same edit independently in each branch, which produces different commit ancestry and later conflicts.

Monitoring

Monitor:

• journey-event persistence failures
• PostHog delivery failures and retry attempts
• duplicate $insert_id values
• event volume by type and environment
• missing $session_id or user_session_id
• signup/onboarding step drop-off
• replay volume and processing gaps
• account/agency attribution gaps

Email telemetry volume belongs in first-party operational reporting, not PostHog Activity.

PostHog dashboard

For the identity/zQA rollout, follow Identity and zQA Filters. Deploy App's extended ingest before the Auth sender, then redeploy Stats and Docs. Native PostHog project filters/cohorts require a separate post-deploy setup; merging code does not activate them. Keep Dev configuration intact.

Create or maintain the internal dashboard Zooly Product Journey — Production. Apply environment = production to every insight and exclude internal_user = true by default.

Recommended insights:

1. Full journey funnel
2. Unique journeys by day
3. Onboarding exits by step
4. Signup/login failures by method and safe error code
5. Errors and timeouts by event
6. Activity by agency and account
7. Replay playlist for errors and incomplete onboarding
8. Delivery health and deduplication

Retry behavior

PostHog delivery is best effort. Failed rows retain attempt state in the database and can be retried in batches. The first-party event ID is reused as $insert_id, so retrying the same row does not create a second logical event in PostHog.

When PostHog is not configured, retries report delivery as disabled rather than changing product behavior. Fix configuration first, then run the authorized retry path.

Change checklist

Before merging a change to analytics or replay:

• add or update event constants instead of hard-coding names in multiple places
• ensure events fire on committed outcomes, not only button clicks
• keep browser actor identity server-resolved
• verify payload sanitization tests
• verify environment normalization tests
• verify replay starts only according to the current product policy
• verify URL sanitization and cross-origin iframe behavior
• test desktop and 390 px Stats layouts when dashboard output changes
• update this documentation when event semantics or variables change

Incident response

If unexpected sensitive data is visible in Replay:

1. Disable Session Replay in the PostHog project immediately.
2. Restrict project access and preserve only the minimum incident evidence.
3. Remove or expire affected recordings according to PostHog controls.
4. Add the required SDK masking/blocking rule and an automated regression test.
5. Deploy to Dev and validate with a new recording.
6. Promote only after security and product owners approve the result.

Disabling Replay does not require disabling sanitized first-party journey events.