| name | cursor-plugin-posthog-exploring-live-traffic |
| description | Inspects PostHog Web analytics Live tab data — current users online, last-30-minutes pageviews, top pages, referrers, devices, browsers, countries, bot traffic, and the per-minute bot/users charts. Use when the user asks \"who is on my site right now?\", \"what is happening live?\", \"what bots are crawling me?\", asks about the \"live tab\" / \"live dashboard\", wants live numbers (last 30 min), |
| metadata | {"version":"0.1.0"} |
Exploring Web analytics live traffic
The Web analytics Live tab (/web/live) shows real-time activity over a 30-minute sliding
window plus a 60-second "users online" count. It is the place to answer "what is happening
on my site right now?" — pageviews, named bots, devices, geo, top paths, top referrers, and
a live event feed.
This skill teaches you (the agent) how to:
- recognize a request that belongs on the Live tab
- read the tile model (what each card shows, where the data comes from)
- manipulate the only filter that exists (host)
- build product-analytics insights that match a Live tile when the user wants
longer time ranges or deeper drill-down than the live window offers
The Live tab is not a HogQL playground — its data comes from a livestream backed by
short HogQL backfills. When the user wants to query "right now" data with HogQL, point
them at the tab; when they want historical breakdowns, build an insight with the patterns
below.
When to use this skill
Use this skill when the user:
- asks "who is on my site right now?", "what is happening live?", "show me live traffic"
- mentions the "Live" tab, the "Live dashboard", or the live page (
/web/live)
- asks about live bot traffic ("which bots are crawling me?", "is GPTBot scraping us?")
- wants to filter live traffic by domain / host
- wants to compare what they see on the Live tab to a longer time window — e.g.
"the live tab shows GPTBot is hammering us, can you give me a 7-day chart of that?"
Do not use this skill for non-realtime web analytics work — for that, use the standard
Web analytics tab (/web).
Tab structure
URL: /web/live
The tab has two filter affordances and a grid of tiles. Date range is fixed: 30 minutes
sliding window for everything except "Users online" (last 60 seconds).
Filters
There is only one filter on the live tab: the host (domain) selector.
- It comes from
webAnalyticsFilterLogic.selectedHost.
- It is shared with the rest of Web analytics, so changing it on
/web propagates to
/web/live and vice-versa.
- It is gated by feature flag
WEB_ANALYTICS_LIVE_DOMAIN_FILTER. If the flag is off, no
host filter UI is rendered and all tiles show data across every domain.
- Setting the host filter narrows: the SSE stream, the HogQL backfill queries (so the
initial 30 min is host-scoped), and the "users online" count.
- There is no date picker, no compare control, no property filters, no test-account
filter on the Live tab. Do not promise the user controls that don't exist.
When the user asks "filter live traffic by domain <host>", direct them to the Domain
selector at the top of the Live tab. There is no URL param to set it directly — it
persists in localStorage via webAnalyticsFilterLogic.
Stat cards (top strip)
| Card | What | Window |
|---|
| Users online | Distinct device IDs seen in the last 60 seconds | 60s |
| Unique visitors | Distinct device IDs in the last 30 min | 30m |
| Pageviews | $pageview count in the last 30 min | 30m |
Content cards
| Card | What | Notes |
|---|
| Active users per minute | Bar chart, new vs returning visitors | last 30 min |
| Top pages | Animated leaderboard, $pathname + view count | top 10, 30 min |
| Top referrers | Animated leaderboard, $referring_domain | top 10, 30 min |
| Devices | Breakdown bars, $device_type | top 6 + Other |
| Browsers | Breakdown bars with logos, $browser | top 6 + Other |
| Top countries | Breakdown bars, $geoip_country_code | top 6 + Other; replaced by a Country/City tab card if WEB_ANALYTICS_LIVE_CITY_BREAKDOWN is on |
| Bot requests per minute | Bar chart, bot events / minute | flag WEB_ANALYTICS_BOT_ANALYSIS |
| Bot traffic | Named bots ranked by event share, with category tag | flag WEB_ANALYTICS_BOT_ANALYSIS; rows are clickable and open an insight for that specific bot |
| Countries (world map) | SVG world map heat | flag WEB_ANALYTICS_LIVE_MAP |
| Live events | Streamed event feed (event, person, URL, timestamp) | last 50 events |
Every tile (except the live event feed and world map) has an "Open as new insight"
button that opens a 7-day Trends query in product analytics. The bot traffic tile rows
are also individually clickable — clicking a bot row opens a single-bot trend.
Bot detection model
Bots are detected server-side. Three virtual properties are attached to the event before
it lands in ClickHouse:
$virt_is_bot — boolean, true if classified as a bot$virt_bot_name — string, the bot's display name (e.g. Googlebot, GPTBot,
Claude, Lighthouse, HeadlessChrome)$virt_traffic_category — string, the category key:
ai_crawler, ai_search, ai_assistant, search_crawler, seo_crawler,
social_crawler, monitoring, http_client, headless_browser, no_user_agent,
regular
The Live bot tiles count "bot-eligible" events: $pageview, $pageleave, $screen,
$http_log, $autocapture. $http_log is included because most bots emit server-side
HTTP logs rather than JS pageviews.
Building product-analytics queries that mirror the Live tab
When the user wants a longer window, a saved insight, a dashboard tile, or to share a
view of what's on the Live tab, build a Trends insight. The "Open as new insight"
buttons in the UI use exactly these recipes:
Bot traffic breakdown (matches the bot tile header)
A single chart of all bots over time, broken down by name. This is the canonical
"who's crawling me?" view.
{
"kind": "TrendsQuery",
"interval": "hour",
"dateRange": { "date_from": "-7d" },
"series": [
{
"kind": "GroupNode",
"custom_name": "Requests",
"operator": "OR",
"math": "total",
"nodes": [
{ "kind": "EventsNode", "event": "$pageview", "math": "total" },
{ "kind": "EventsNode",
Single bot drill-down (matches a clicked bot row)
{
"kind": "TrendsQuery",
"interval": "hour",
"dateRange": { "date_from": "-7d" },
"series": [
],
"properties": [
{ "key": "$virt_is_bot", "value": ["true"], "operator": "exact", "type": "event" },
{ "key": "$virt_bot_name", "value": ["GPTBot"], "operator"
The category filter is optional — include it when the user asks about a specific
bot+category combo (Lighthouse · headless_browser is a different signal from
Lighthouse · monitoring).
Bot category breakdown (matches the bot events chart tile)
Use breakdown by $virt_traffic_category instead of $virt_bot_name when the user
wants "AI crawlers vs SEO crawlers vs everything else" rather than per-bot rows.
Top pages / referrers / devices / browsers / countries
For non-bot tiles, use $pageview with math: unique_users, breakdown by the
underlying property:
| Tile | breakdown property | display |
|---|
| Top pages | $pathname | ActionsBarValue |
| Top referrers | $referring_domain | ActionsBarValue |
| Devices | $device_type | ActionsPie |
| Browsers | $browser | ActionsPie |
| Countries | $geoip_country_code | WorldMap |
Always inherit the live tab's host filter when the user is asking about a specific
domain — add { "key": "$host", "value": ["<host>"], "operator": "exact", "type": "event" }
to properties.
Defaults to use
dateRange.date_from: -7d unless the user names a window — the live view itself
is 30 min, but the user is almost always asking about a longer window when they
request an insight version.interval: hour for 7-day windows, minute only for windows under a day,
day for windows beyond 14 days.- Always inherit the host filter when one is set on the Live tab. Don't drop it
silently — that changes the answer.
Common requests and the right move
| User says | Right move |
|---|
| "What's happening on the site right now?" | Send them to /web/live |
"Filter live traffic to example.com" | Use the Domain selector at top of /web/live |
| "Show me bots crawling us in the last 30 min" | /web/live → Bot traffic tile |
| "Show me bots crawling us this week" | Build the "Bot traffic breakdown" insight above with date_from: -7d |
| "How much is GPTBot hitting us?" | Build the "Single bot drill-down" insight, set $virt_bot_name to GPTBot |
| "Why is the live tab showing X but my dashboard shows Y?" | The live tab is a 30-min sliding window over events; dashboards aggregate over the picked range. They are not directly comparable beyond the last 30 min. |
| "Add a date range to the live tab" | The Live tab has no date picker — for ranges, build a Trends insight using the patterns above |
| "Filter live traffic by browser / device / country" | Not supported — only the host filter exists. Build a Trends insight with the relevant breakdown + filter instead |
Gotchas
- Bot virtual properties (
$virt_*) only exist on events processed by the bot
classification step. They are not retroactive — events from before the classifier
shipped will not have them. Keep dateRange.date_from within the last few months
for reliable bot results.
$http_log events come from server-side log capture, not from posthog-js. If a
project does not emit $http_log, bots that don't run JS (most crawlers) will be
invisible to the bot tiles.- The 30-minute window is a sliding aggregation over an in-memory buffer in the
browser — refreshing the page replays the backfill HogQL, not the SSE stream. Do
not interpret a brief "0" right after page load as a real drop.
- The host filter strips the protocol — pass
example.com, not https://example.com.
- Tile order is persisted per-team in
localStorage (under feature flag
WEB_ANALYTICS_LIVE_EDIT_LAYOUT). If a user's layout looks different from yours,
it is not a bug.
