Analytics Instrumentation

Every product EGI builds ships with analytics instrumentation. This is not optional. Analytics provide the data needed to measure product success, identify issues, and make informed decisions about future development.

EGI uses PostHog as the standard analytics platform.

PostHog Setup

Initial Configuration

Every project must complete the following during the Build phase:

1. Create a PostHog project for the application (one project per product, not per environment)
2. Install the PostHog SDK appropriate for the project's tech stack:
   • Next.js / React: posthog-js + posthog-node (for server-side)
   • Node.js backend: posthog-node
   • Mobile: PostHog iOS or Android SDK
3. Configure environment separation -- Use PostHog's environment or project token configuration to distinguish between staging and production events
4. Set the PostHog API key as an environment variable (NEXT_PUBLIC_POSTHOG_KEY or equivalent); never hardcode it
5. Enable autocapture as a baseline, then layer on custom events for critical flows

Privacy and Compliance

• Respect Do Not Track (DNT): Configure PostHog to honor DNT browser settings if the project requires it
• IP anonymization: Enable IP anonymization unless there is a documented reason to retain full IP addresses
• Cookie consent: If the product serves users in jurisdictions requiring consent (e.g., GDPR), implement a consent banner and only initialize PostHog after consent is granted
• Sensitive data: Never send personally identifiable information (PII) such as passwords, payment details, or government IDs as event properties

Event Tracking

Required Events by Project Type

All projects must track:

Event	Description	When to Fire
page_view	User views a page	On every page/route change (autocapture handles this)
sign_up	User creates an account	After successful account creation
sign_in	User logs in	After successful authentication
sign_out	User logs out	After logout completes
error_displayed	An error message is shown to the user	When an error UI element renders

SaaS / web applications additionally track:

Event	Description	When to Fire
onboarding_started	User begins the onboarding flow	On first step of onboarding
onboarding_completed	User finishes onboarding	On final step completion
feature_used	User engages with a core feature	On meaningful interaction with each major feature
export_completed	User exports data	After successful export
settings_changed	User modifies a setting	After settings are saved

E-commerce or transactional projects additionally track:

Event	Description	When to Fire
item_added_to_cart	User adds an item	On add-to-cart action
checkout_started	User begins checkout	On checkout page load
purchase_completed	Transaction completes	After payment confirmation

Event Naming Conventions

• Use snake_case for all event names (e.g., sign_up, not SignUp or sign-up)
• Start with a verb or noun that describes the action or object (e.g., form_submitted, report_generated)
• Be specific -- prefer invoice_downloaded over download_clicked
• Use a consistent prefix for related events (e.g., onboarding_started, onboarding_step_completed, onboarding_completed)
• Do not include dynamic values in event names (e.g., use page_view with a page_name property, not page_view_dashboard)

Event Properties

Every custom event should include relevant properties to make the data useful for analysis.

posthog.capture('feature_used', {
  feature_name: 'report_builder',
  action: 'generate',
  report_type: 'monthly_summary',
  duration_ms: 2340
})

Standard properties to include when applicable:

• feature_name -- Which feature the event relates to
• action -- The specific action taken (e.g., create, update, delete, view)
• source -- Where the user came from or how they triggered the action (e.g., sidebar, search, notification)
• duration_ms -- How long the action took (for performance-sensitive events)
• success -- Boolean indicating whether the action succeeded (for actions that can fail)
• error_type -- If the action failed, what kind of error occurred

User Identification

Identifying Users

Call posthog.identify() when a user signs in or when their identity becomes known.

posthog.identify(user.id, {
  email: user.email,
  name: user.name,
  role: user.role,
  company: user.companyName
})

• Use the application's internal user ID as the distinct ID (not email)
• Set person properties that are useful for segmentation (role, company, plan type)
• Call posthog.reset() on sign-out to prevent event blending between users on shared devices

Anonymous Users

PostHog automatically assigns an anonymous ID before identification. After identify() is called, PostHog merges the anonymous and identified profiles. No additional configuration is needed.

Feature Flags

Feature flag instrumentation is covered separately. See Feature Flags for naming conventions, rollout strategies, and cleanup policies.

For analytics purposes, ensure that feature flag evaluations are captured as events so you can compare behavior between flag variants.

Session Replay

When to Enable

• Always enable on staging environments for QA and debugging
• Enable on production for new products during the first 30 days post-launch (stabilization period)
• Disable or sample on production after stabilization to manage data volume (e.g., record 10% of sessions)

Configuration

• Set a reasonable session recording sample rate in PostHog (100% for staging, 10--25% for production post-stabilization)
• Mask sensitive input fields (passwords, payment details) using PostHog's masking configuration
• Set a session recording retention period appropriate for the project (default: 30 days)

Dashboards

Required Dashboards

Every project must have the following PostHog dashboards configured before launch:

1. Product Overview -- Key metrics at a glance:

   • Daily/weekly/monthly active users
   • Sign-up conversion rate
   • Core feature adoption (percentage of users who have used each major feature)
   • Error rate trend

2. Funnel Performance -- Critical user funnels:

   • Sign-up funnel (landing page to account creation)
   • Onboarding funnel (account creation to onboarding complete)
   • Core conversion funnel (specific to the product's primary value action)

3. Technical Health -- Performance and reliability:

   • Client-side error rate
   • Page load time trends
   • API response time trends (if instrumented)

Dashboard Naming

Name dashboards with the project name prefix for easy discovery:

• [Project] - Product Overview
• [Project] - Funnel Performance
• [Project] - Technical Health

Dashboard Review Cadence

• Weekly: Project lead reviews the Product Overview dashboard during sprint planning
• Monthly: Full dashboard review with the team to identify trends and opportunities
• On-demand: After any release, check the Technical Health dashboard for regressions