Skip to content

Count requests to the docs agent addresses in PostHog #578

Closed

Description

@aicayzer

Summary

Count requests to the docs site's agent addresses in PostHog, so the maintainers can see which agents read the docs and what they read.

Context

Both sites send page views and unhandled errors to one PostHog project from the browser, after hydration (src/lib/analytics.ts, src/components/analytics.tsx). An agent that fetches a .md page, /llms.txt, /mcp or /api/docs/search runs no browser script, so none of these requests is counted today. src/AGENTS.md ("Analytics") says the sites send page views and errors and nothing else.

Acceptance criteria

  • The Worker sends one PostHog event for each request to /mcp, /api/docs/*, *.md, /llms.txt, /llms-full.txt and /docs-map.md.
  • The event carries the path, the surface (Markdown copy, index, MCP, search, topics), the client name from the User-Agent and, for MCP, the client name and tool name the client reports. For a search it also carries the number of hits.
  • The event carries no IP address, cookie or person profile, so neither site needs a consent banner.
  • Sending the event never slows or fails the request (the Worker does not wait for it), and a build without MARFA_POSTHOG_KEY sends nothing, as today.
  • src/AGENTS.md ("Analytics") and the options comment in src/lib/analytics.ts say what is sent, and a test pins it.

Out of scope

  • The text of a search query.
  • Counting people, or any new browser capture.

Notes

I did not check PostHog's documentation for how to send an event without creating a person profile (the $process_person_profile property is what I expect). Read the current PostHog docs before building. Recording query text would show what readers cannot find, but it is typed content, so it needs its own decision.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions