fix(analytics): the bot site was recording nothing

[MarkusNeusinger]

Symptom

bots.anyplot.ai showed 0 events after the tracking deployed, despite live traffic through the instrumented path.

Cause 1 — Plausible drops bot user agents

Verified by probing the live API and comparing what appeared, rather than inferred:

Event sent as	Landed?
Claude-User/1.0	❌
Chrome browser UA	✅
anyplot-server/1.0 + identity in props	✅

All three returned 202 ok. Plausible always acknowledges, then discards — which is why nothing surfaced as an error and why the Cloud Run logs were clean.

Forwarding the real crawler agent therefore guaranteed an empty dashboard. Their docs describe no way to opt an event back in, so machine-side events now travel under a neutral agent. Nothing is lost: the docs say the UA feeds user_id and the Browsers/OS/Devices tabs — meaningless for a crawler — while the identity that matters already rides in assistant and kind.

Cause 2 — found by reading their docs, latent but real

"If you forward a server, hosting provider, or CDN IP address instead of the actual visitor IP, Plausible's bot filtering will drop the event." … "the first valid IP address from the list is used"

Analytics was reusing client_ip from the feedback rate limiter, which returns the rightmost forwarded entry on purpose: the leftmost is client-controlled, and trusting it once let a caller poison another user's rate-limit bucket. For analytics that rule is exactly inverted — the rightmost entry is our own infrastructure, which Plausible discards.

In production cf-connecting-ip is present and covers both, so this was latent rather than active. The fallback would have thrown events away silently.

Analytics now has its own visitor_ip. api/request_context.py spells out why the two must not be merged, because merging them is the obvious tidy-up and it breaks one of the two callers every time.

Verification

• Both resolvers checked side by side: with cf-connecting-ip they agree; without it visitor_ip → 203.0.113.7 (the visitor) and client_ip → 10.0.0.9 (ours), which is the intended divergence
• pytest tests/unit — 1641 passed, including three new tests: bot_fetch must not forward the crawler agent, machine-side og_image_view uses the neutral one, and main-site og_image_view still sees the real Twitterbot/1.0
• ruff check + ruff format --check — clean

Note

Three probe events (/diag2, /diag3) are sitting on bots.anyplot.ai from the diagnosis. The site had no other data, so they are harmless, but they are not real traffic.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes server-side Plausible analytics for the bot site (bots.anyplot.ai) where events were being silently dropped (while still returning HTTP 202), by ensuring machine-side events are sent with a neutral User-Agent and by reporting the visitor IP (not infrastructure IP).

Changes:

• Add a neutral sender User-Agent (BOT_SENDER_UA) for events recorded to bots.anyplot.ai.
• Introduce a dedicated visitor_ip() resolver for analytics and switch analytics tracking to use it.
• Add unit tests + documentation updates describing Plausible’s silent-drop behavior; add a changelog entry.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
api/analytics.py	Sends bot-site events with a neutral UA and switches analytics IP resolution to visitor_ip().
api/request_context.py	Adds visitor_ip() to resolve the visitor address for analytics (distinct from rate-limiting).
tests/unit/api/test_analytics.py	Updates IP expectations and adds coverage ensuring bot-site events use the neutral UA.
docs/reference/plausible.md	Documents two Plausible silent-drop conditions (bot UA, infrastructure IP).
CHANGELOG.md	Records the bot analytics fix and the rationale under Fixed.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 95.65217% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
api/request_context.py	94.44%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (4)

api/request_context.py:60

• visitor_ip says it follows Plausible's "first valid IP" rule, but it currently returns the first non-empty XFF entry without validating that it is an IP address. If a proxy inserts placeholders like unknown (or a client forges a non-IP first entry), we'll forward an invalid value to Plausible and can silently lose geolocation/bot-filtering behavior again.

    cf_ip = request.headers.get("cf-connecting-ip", "").strip()
    if cf_ip:
        return cf_ip
    for entry in request.headers.get("x-forwarded-for", "").split(","):
        if entry.strip():

docs/reference/plausible.md:263

• The phrase "HTTP 202 ok" is inaccurate (202 is "Accepted"); keeping the correct status text helps future debugging when comparing responses from the Events API.

Both were found by sending probe events against the live API and comparing what
appeared, and both make an event vanish with an HTTP `202 ok` — Plausible always
acknowledges, then discards.

CHANGELOG.md:239

• The changelog entry mentions "202 ok", but HTTP 202 is "Accepted". Using the correct status name avoids confusion when correlating with logs and HTTP clients.

  discards their events, so forwarding the real one guaranteed an empty dashboard. Verified against
  the live API: the same event sent as `Claude-User` never appears, sent as a browser agent it does,
  and both are acknowledged with `202 ok` — Plausible always accepts, then drops. There is no
  documented bypass, so machine-side events now travel under a neutral agent; nothing is lost,

tests/unit/api/test_analytics.py:495

• Test class name reads awkwardly in CamelCase ("UseA..."). Renaming improves readability and makes it easier to search for related tests.

class TestBotEventsUseANeutralAgent:

[MarkusNeusinger]

Applied, and the wording in Plausible's own docs backs it: they use "the first valid IP address from the list". Returning an unvalidated token meant a proxy-inserted unknown would be forwarded verbatim and the event discarded or mis-located — which is the exact failure mode this PR exists to remove, so it would have been a quiet own-goal.

Malformed entries are now skipped rather than passed on, IPv6 included, falling through to the socket peer when nothing in the chain is usable. Five parametrised cases cover it.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

docs/reference/plausible.md:262

• The HTTP status phrasing 202 ok is not a standard reason phrase for 202 responses and reads like a typo; consider using 202 Accepted (or just 202) for accuracy.

appeared, and both make an event vanish with an HTTP `202 ok` — Plausible always

CHANGELOG.md:238

• The changelog entry says Plausible returns 202 ok, but 202 responses are typically 202 Accepted; using the standard phrasing avoids confusion.

  and both are acknowledged with `202 ok` — Plausible always accepts, then drops. There is no