docs(ai-gateway): make the analytics counting basis explicit (requests vs attempts vs cache hits)

[roy-tong]

Summary

Adds a Counting basis section to the AI Gateway analytics reference, defining what the Requests / Tokens / Cost metrics count per event shape: plain request, gateway retry, cross-provider fallback, and cache hit with zero provider attempts.

Follows the direction agreed in #32983:

• four-case table mapping each event shape to log rows, provider attempts, the Requests metric, and token/cost attribution;
• two audit rules: attempts and requests are separate grains (reliability reads attempts, demand reads requests), and a metric whose counting basis is not stated should be treated as not yet defined, never assumed;
• current built-in behavior is labeled as observed from the outside and pending maintainer confirmation wherever the public docs did not previously define it, so reviewers can evaluate concrete wording rather than intent.

Notes for reviewers

• The intent is definitional, not behavioral: no product behavior is described as changed.
• Wording for rows marked observed is deliberately conservative and should be confirmed against the backend; anything maintainers can confirm can drop the observed qualifier.

Closes #32983

[cloudflare-docs-bot]

Review

💡 1 suggestion found in commit 16712cd.

👉 Fix in your agent 👈

Fix the following review findings in PR #33414 (https://github.com/cloudflare/cloudflare-docs/pull/33414).

Before making changes, review each finding and present a brief summary table:
- For each finding, state whether you agree, disagree, or need clarification
- If you disagree (e.g. the fix requires disproportionate effort for minimal benefit,
  or the finding is factually incorrect), explain why
- If you need clarification before deciding, ask those questions
- Then share your plan for which issues to tackle and in what order

After triaging, follow this order:
1. Post a comment on this PR for any findings you are skipping, with the finding ID and your reasoning.
2. Then commit the fixes for the legitimate findings.

The comment must come before the commit — the bot reads PR comments when a new
push triggers a review, so skip comments posted after the push will be missed.

---

## Code Review

### Suggestions (1)

#### CR-57a99d91652d · Inconsistent rule count
- **File:** `src/content/docs/ai-gateway/observability/analytics.mdx` line 38
- **Issue:** The intro on line 38 says "Two rules keep these numbers auditable:" but the following list contains three bullet items (lines 38-40), and bullets 2 and 3 restate nearly the same idea (an unstated counting basis is undefined/pending definition).
- **Fix:** Change the intro to "Three rules..." or merge the third bullet into the second so the count matches the list.

Code Review

This code review is in beta and may not always be helpful — use your judgment.

Suggestions (1)

File	Issue
ai-gateway/observability/analytics.mdx line 38	Inconsistent rule count — The intro on line 38 says "Two rules keep these numbers auditable:" but the following list contains three bullet items (lines 38-40), and bullets 2 and 3 restate nearly the same idea (an unstated counting basis is undefined/pending definition). Fix: Change the intro to "Three rules..." or merge the third bullet into the second so the count matches the list.

Conventions

_{No convention issues found.}

Style Guide Review

_{No style-guide issues found.}

Commands

Only codeowners can run commands. Post a comment with the command to trigger it.

Command	Description
/review	Runs a review now. Incremental if a prior review exists, full if not.
/full-review	Re-reviews the entire PR diff from scratch, ignoring incremental history. Useful after a rebase, when you want a fresh review, or if the bot gets out of sync and reports issues that no longer exist.
/ignore-review-limit	Permanently lifts the 2-review automatic limit for this PR. Future pushes will trigger reviews as normal.
/disable-auto-review	Stops automatic reviews from triggering on future pushes to this PR. Codeowners can still run /review or /full-review manually.
/rebase	Rebases the PR branch against production. On conflict, attempts to resolve automatically using AI. Stops with an explanation if confidence is not high enough.

[shawnbure]

Thanks for turning the issue into a concrete reviewable artifact. The request/attempt separation and the four event shapes are the right structure.

One evidence-boundary change is still needed before this can be treated as an auditable definition: the table currently states exact behavior as fact, while the PR description says those behaviors are observed or pending maintainer confirmation. Please add a Definition status column (for example, documented / backend-confirmed / observed / pending confirmation) and apply it per row or per cell.

The highest-risk cells are:

• retry: “2” log rows and “1 request”;
• fallback: one row per provider attempt and “1 request”;
• retry/fallback token and cost attribution;
• cache hit: “1” log row, counted as a served request, and zero cost contribution.

Until maintainers confirm those units, I would phrase them as proposed/observed and avoid “sum of what providers billed,” which can imply a billing guarantee. A safer interim form is “displayed attribution is pending backend confirmation; do not use for billing or enforcement.”

That change would make the UNPROVABLE rule operational instead of leaving it only in prose.

[roy-tong]

Pushed 16712cd per your review: added a Definition status column (observed / pending confirmation, with backend-confirmed reserved for maintainers), removed the billing-guarantee phrasing - cost cells now say displayed cost attribution, and the rules state that displayed attribution must not be used for billing or enforcement until backend-confirmed. The not-yet-defined rule now names the statuses instead of leaving them in prose. Also applied the docs-bot wording fixes. The risky cells you called out (retry rows/requests, fallback attribution, cache-hit cost) are all marked pending confirmation.

[shawnbure]

The Definition status column and removal of the provider-billing guarantee address the evidence boundary in my September 14 review. Thank you for making those changes in 16712cd.

One remaining presentation risk: the pending-confirmation rows still read as exact definitions when the table is excerpted without the rules below it. Please label those cell values as proposed (or put a short “proposed counting basis; not backend-confirmed” sentence immediately before the table). That will preserve the boundary when someone quotes the table in a report. I agree with the bot's small wording correction: merge the final bullet into the second, or change “Two rules” to “Three rules.”

The request/attempt distinction is useful; this review does not verify the proposed backend behavior. Maintainer confirmation remains the prerequisite for treating the rows as a product definition or using their cost attribution for billing or enforcement.