Skip to main content

Miru product analytics

Set POSTHOG_HOST to the HTTPS instance URL and POSTHOG_PROJECT_TOKEN to the Miru project's public capture token on both web and worker processes. A personal API key must never be used here. Missing either setting disables this integration. The layout supplies the public settings at runtime; a frontend rebuild is not needed to change projects.

The browser uses the official posthog-js SDK for SPA pageviews, masked autocapture, web vitals, exceptions, session replay, heatmaps, surveys and feature-flag evaluation. Enable replay, heatmaps, dead-click capture, web vitals, exception capture and surveys in the project's settings. Product tours require a published tour, and experiments require a flag and a defined goal. These controls do not change Miru's plan permissions.

Use https://app.miru.so for both the project's app URL and recording domain. The current receiver expects recording domains as full URLs; a bare hostname silently disables replay in the public SDK configuration. Verify that replay configuration is returned with Miru's Origin header and disabled for an unrelated origin before enabling capture in production.

Publish the optional feedback widget only on the intended product routes. Keep authentication, payroll, employee records, signing and hiring review pages out of survey targeting. Paid Cloud-only features and separately configured AI or messaging providers are not enabled by installing the browser SDK.

People use miru:user:<id> and the company group uses miru:company:<id>. Names, emails and client/invoice content are excluded from backend capture. Attribution values containing emails, URLs or credential assignments are dropped before enqueueing, again at delivery, and from browser campaign properties. Automatic campaign/referrer persistence is disabled because feature-flag requests bypass event filtering. Startup removes legacy initial attribution before flags load and registers only safe campaign values; flags and surveys remain enabled. Replay masks text, attributes and inputs, blocks documents and media, and stops on authentication, profile, settings, team, payroll, employee, hiring and shared invoice pages. Network bodies, headers and console recording are disabled. Event and replay URLs lose query strings and fragments. Do Not Track is respected. Heatmap URL keys and initial/previous-page pathnames are sanitized too. Visits to different records still count separately while exported URLs use :id placeholders.

The official posthog-rails integration captures Rails and background-job exceptions. Exception messages, source snippets, request parameters and absolute source paths are removed; exception types and source locations remain useful for grouping. Backend exceptions use the same authenticated user identity as the browser, or the non-person miru:backend identity.

PostHog Logs receives structured controller, SQL-operation, Active Job and mailer notifications through the official OpenTelemetry exporter. SDK batching and its 6,000-record per-minute cap bound forwarding. The log filter keeps operation metadata and authenticated user/workspace IDs. SQL statements, job arguments, request parameters, raw messages and arbitrary Rails.logger output are excluded. Browser navigation also produces a miru.page_view structured log with a sanitized URL and SDK session/person correlation. Console capture remains off. Structured notifications use the SDK's debug threshold to include SQL operation names; forwarding the Rails logger remains disabled. Web-vitals metrics retain numeric values and discard attribution objects that can contain navigation URLs.

Test mode disables SDK network calls. Missing runtime settings also leave the Rails SDK uninitialized. Both web and worker processes need the settings and a restart when enabled.

An HTTPS configuration error names POSTHOG_HOST: correct the instance URL and restart web and worker, or unset the setting to disable PostHog. For a capture HTTP error, check collector health, the host and the public project capture token. Delivery makes at most five attempts with the same UUID; inspect failed jobs after those attempts. Response bodies and credentials are excluded from error messages.

Existing Rails product events supply workspace/client/project creation, time entries, invoices, payments, invitations, expenses and imports. The existing tracking service supplies signup attribution, trials and subscription conversion. Delivery uses Active Job after commit, retries failures and reuses the job UUID for deduplication. Only approved property keys reach the queue or PostHog.

Build a Miru growth dashboard with:

  • Signup to activation: user_signup → workspace_created → project_created → time_entry_created.
  • Sales: trial_started → subscription_checkout_started → subscription_purchased, broken down by signup UTM source and campaign.
  • Invoicing: invoice_created → invoice_sent → payment_recorded.
  • Weekly active users and retention from time_entry_created.
  • Browser exceptions and replay links for the failing routes.

Subscription conversion events without a user belong to the company identity; analyze the sales funnel by company rather than treating those as user events. Group association requires person processing, so these events create company service profiles. Filter human analytics to distinct IDs beginning miru:user:. Financial payment events describe use of Miru's invoicing feature; they are not Miru subscription revenue. No historical events are backfilled automatically.

Self-hosting​

Deploy and verify the receiver before enabling capture in Miru. PostHog's current official hobby stack has about 47 services and a published requirement of 16 GB RAM. A shared app host needs additional capacity for its existing apps.

Deploy the current official hobby stack with its proxy bound to a free loopback port behind the existing TLS proxy, rather than taking ports 80/443. Remove the upstream development port publications for databases and internal services. Keep its volumes and secrets separate from the Rails apps and configure backups before relying on it. Self-hosting has no PostHog support guarantee; some AI features also need separately configured provider credentials.

References: self-hosting, capture API, replay privacy.

Local checks​

Use an isolated local database for the new job/subscriber specs and the existing subscription purchase delivery specs. Run the required timeout 30 bin/vite build, focused TypeScript checking, ESLint and RuboCop.

With a local app on port 3179 configured for the synthetic token phc_synthetic and host https://posthog.example.test, run node scripts/qa/posthog.test.mjs. It uses Brave, intercepts analytics locally, and checks signup rendering, URL redaction, user/workspace identity, guest reset, disabled configuration and an unavailable analytics server. It inspects recorder payloads for masked inputs and text and verifies replay stopping on a settings SPA transition in Brave. Flag-request assertions cover fresh visits and legacy attribution persistence. Separate unit assertions check the application's HR, payroll and team route exclusions. These are local SDK checks, not proof that a PostHog server ingested an event.