mongo-ai/posthog-web-analytics-diagnosis

Web analytics diagnosis workflow

Before you diagnose: fetch live docs

1. Run docs-search("web analytics troubleshooting {specific symptom}")
2. If setup-related: run docs-search("web analytics installation {framework}")
3. If potential known bug: run gh search issues --repo PostHog/posthog-js "web analytics {symptom}"
4. Use the fetched docs as your primary reference — NOT the steps below

The steps below are a diagnostic FRAMEWORK (what questions to ask, in what order). The docs responses are the CONTENT (current answers, version requirements, config details).

Goal

Determine whether the web analytics problem is caused by:

• missing or misconfigured SDK installation
• no $pageview events being captured
• reverse proxy not set up (ad blockers dropping events)
• UTM parameters not being captured or attributed
• bounce rate / session duration inaccuracy
• discrepancy with Google Analytics or other tools
• channel type misattribution
• framework-specific SPA routing issue
• known product bug

Step 1: Verify events are arriving

Web analytics relies on $pageview, $pageleave, and autocapture events.

SELECT event, count()
FROM events
WHERE event IN ('$pageview', '$pageleave', '$autocapture')
  AND timestamp > now() - interval 7 day
GROUP BY event
ORDER BY count() DESC;

If zero $pageview events → SDK not installed or not capturing. Go to Step 2. If $pageview exists but numbers look wrong → Go to Step 3.

Step 2: SDK installation issues

Run docs-search("web analytics installation {framework}")

Key areas to investigate:

• Is posthog-js initialized correctly?
• Is capture_pageview enabled? (it's true by default, but may be manually disabled)
• For SPAs (React, Next.js, Vue, etc.): is the router integration capturing navigation?
• Is capture_pageleave enabled? (needed for bounce rate and session duration)
• SDK version — check against minimum for web analytics features

-- Check SDK version in use
SELECT properties.$lib, properties.$lib_version, count()
FROM events
WHERE timestamp > now() - interval 7 day
GROUP BY properties.$lib, properties.$lib_version
ORDER BY count() DESC;

SPA-specific issues

| Framework | Common issue | Fix | |-----------|-------------|-----| | Next.js App Router | No pageviews on client navigation | Need PostHog provider with router integration | | React Router | Only captures initial load | Need useLocation() listener to capture navigations | | Vue Router | Same as above | Need router.afterEach() hook | | Nuxt | SSR vs client mismatch | Need client-only plugin initialization |

Step 3: Data accuracy issues

Missing or low pageview counts

• Ad blockers — if no reverse proxy, ad blockers will drop PostHog requests
  • Run docs-search("reverse proxy setup PostHog ad blocker")
  • Typically 10-30% of traffic is lost to ad blockers without a proxy
• Bot filtering — PostHog filters known bots; GA may not (or vice versa)
• SPA routing — client-side navigations may not be captured (see Step 2)
• Test account filtering — check if internal traffic is being filtered out

Bounce rate issues

Bounce rate requires both $pageview and $pageleave events.

-- Check if pageleave events are being captured
SELECT count()
FROM events
WHERE event = '$pageleave'
  AND timestamp > now() - interval 7 day;

If zero $pageleave → capture_pageleave is likely disabled or SDK is too old.

Run docs-search("web analytics bounce rate pageleave")

Session duration issues

Session duration is calculated from $start_timestamp to $end_timestamp on the sessions table.

-- Check session durations
SELECT
  avg($session_duration) as avg_duration,
  median($session_duration) as median_duration,
  max($session_duration) as max_duration
FROM sessions
WHERE $start_timestamp > now() - interval 7 day;

Step 4: Attribution and UTM issues

Missing UTM parameters

-- Check if UTM data is being captured
SELECT
  properties.$utm_source as utm_source,
  properties.$utm_medium as utm_medium,
  properties.$utm_campaign as utm_campaign,
  count()
FROM events
WHERE event = '$pageview'
  AND timestamp > now() - interval 7 day
  AND properties.$utm_source IS NOT NULL
GROUP BY utm_source, utm_medium, utm_campaign
ORDER BY count() DESC
LIMIT 20;

If zero UTMs → check if the marketing URLs actually contain UTM params, or if a redirect is stripping them.

Channel type misattribution

Run docs-search("web analytics channel type attribution")

PostHog uses session entry properties for channel classification. Check:

SELECT $channel_type, count()
FROM sessions
WHERE $start_timestamp > now() - interval 7 day
GROUP BY $channel_type
ORDER BY count() DESC;

If most traffic shows as "Direct" when it shouldn't → referrer may be stripped by:

• HTTPS → HTTP downgrades
• Referrer-Policy headers
• Meta referrer tags
• Redirect chains stripping the referrer

Step 5: Discrepancies with other analytics tools

Common reasons PostHog and GA/other tools show different numbers:

| Difference | Why | |-----------|-----| | PostHog shows fewer pageviews | Ad blockers blocking PostHog but not GA (via GTM) | | PostHog shows more pageviews | GA sampling data; PostHog doesn't sample | | Different bounce rates | Different definitions — PostHog uses $pageleave, GA uses interaction events | | Different session counts | Different session timeout windows (PostHog: 30min, GA: 30min default but configurable) | | Different user counts | Different identity resolution — cookies, cross-device tracking | | UTM attribution differs | Different attribution models (PostHog: session entry, GA: last click by default) |

The most common cause is ad blockers. Recommend reverse proxy to close the gap.

Step 6: Search known issues

Search GitHub with at least 2 variants:

• gh search issues --repo PostHog/posthog-js "web analytics {symptom}"
• gh search issues --repo PostHog/posthog "web analytics {symptom}"

Common resolution patterns

• No web analytics data at all → SDK not installed, capture_pageview disabled, or wrong project token
• Low numbers vs other tools → ad blockers, need reverse proxy
• No bounce rate → $pageleave not captured, enable capture_pageleave
• Wrong channel attribution → referrer being stripped, check Referrer-Policy headers
• SPA only captures first page → missing router integration for client navigations
• UTMs missing → redirects stripping query params, or UTMs not in the landing URL