Skip to content

feat(telemetry): GeoIP, environment classification, person profiles, website analytics - #2

Merged
DibbayajyotiRoy merged 1 commit into
mainfrom
fix/posthog-geoip
Oct 7, 2026
Merged

DibbayajyotiRoy merged 1 commit into
mainfrom
fix/posthog-geoip

Conversation

@DibbayajyotiRoy

Copy link
Copy Markdown
Owner

Summary

Library usage analytics (@ahtmljs/schema)

  • GeoIP on. Events carry approximate country and city. No $ip is sent, and the PostHog project discards client IPs.
  • Environment classification on every event:
    • env_class: test, ci, build, serverless, dev, server, cli_interactive, browser or unknown.
    • Also ci_provider, hosting, is_tty, is_container, node_env and package_manager.
    • Only fixed labels and booleans are sent. A test asserts that environment-variable values never leak.
  • $session_id (UUIDv7), one per process.
  • Anonymous person profiles, keyed by the anonymous install id, with first and last env_class, package, version, runtime and OS. This enables cohorts, lifecycle, retention and stickiness.
  • error.<code> events from AHTMLError: the code only, never the message.

Landing site

  • PostHog web analytics: in-memory persistence (no cookies, nothing stored in the browser), a /ingest reverse proxy, heatmaps, web vitals, no session recording, production only.
  • The privacy page now covers website analytics, package usage analytics and Scarf. The stale Google Analytics claim is removed.

PostHog project (already configured, outside this diff)

  • An "AHTML usage" dashboard with 16 insights.
  • Test-account filters: CI, build, test, the dev machine and e2e.* events.
  • A "real users" cohort and the "AHTML real usage" and "AHTML errors" actions.

Merging triggers the auto-release of the next patch, after which new installs report the richer data.

Before merging

  • PostHog → Settings → Project → Discard client IP data is on.
  • Do not enable "Cookieless server hash mode" (it would strip GeoIP).

Test plan

  • npm run build:packages
  • npm test: 689 pass, 0 fail
  • npm run smoke:imports
  • npm run test:conformance: 63 pass, 0 fail
  • npm run build -w examples/landing and type-check: no PostHog calls during build
  • Live probes e2e.geo_probe and e2e.env_probe → https://eu.i.posthog.com/batch/ 200 OK
  • Headless Chrome check of the landing site: no cookies, no localStorage or sessionStorage
  • After deploy, a real $pageview does not carry $internal_or_test_user
  • After release, the dashboard shows real installs by country and environment

…website analytics

Library usage analytics (@ahtmljs/schema telemetry):
- Enable PostHog GeoIP: stop sending $geoip_disable so events carry
  approximate country/city. Client IPs are discarded by the project.
- Classify every event's environment so real users can be separated from
  CI/build/test traffic: env_class, ci_provider, hosting, is_tty,
  is_container, node_env, package_manager. Enum/boolean values only; env var
  values are never sent.
- Per-process $session_id (UUIDv7).
- Anonymous person profiles keyed by the anonymous install id, with
  first/last env_class, package, version, runtime and OS, enabling cohorts,
  lifecycle, retention and stickiness.
- error.<code> events from AHTMLError (code only, no message).

Landing site:
- PostHog web analytics with in-memory persistence (no cookies, nothing
  stored in the browser), reverse proxy via /ingest, heatmaps and web
  vitals, no session recording, production only.
- Privacy page covers website analytics, package usage analytics and Scarf;
  removes a stale Google Analytics claim.

Docs: README usage-analytics fields, docs/agents.md, CHANGELOG.
@vercel

vercel Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
ahtmljs Ready Ready Preview Oct 7, 2026 8:20pm UTC

@DibbayajyotiRoy DibbayajyotiRoy self-assigned this Oct 7, 2026
@DibbayajyotiRoy
DibbayajyotiRoy merged commit ac1432c into main Oct 7, 2026
5 of 6 checks passed

This branch was successfully deployed

1 active deployment
Preview — 5d9ede12 Deployed Oct 7, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant