Adding documentation for analytic-header-filter policy

[O-sura]

Purpose

• This PR adds the documentation for the analytics-header-filter policy added for control which request and response headers are included in analytics data using allow or deny modes.

• Related to: Implement Analytics specific policy #361

Summary by CodeRabbit

• Documentation
  • Added documentation for an Analytics Header Filter policy to control which request and response headers are recorded in analytics (allow/deny modes, independent request/response settings). Includes configuration details, system prerequisites, API usage examples, common use cases (sensitive data protection, noise reduction, compliance, cost savings), and clarifies it only affects analytics collection, not runtime traffic.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Adds two new documentation pages that describe the Analytics Header Filter policy, which configures independent allow/deny lists for request and response headers to be filtered from analytics data; matching is case-insensitive and the policy affects analytics collection only.

Changes

Cohort / File(s)	Summary
Analytics Header Filter Documentation docs/ai-gateway/analytics/analytics-header-filter.md, docs/gateway/analytics/analytics-header-filter.md	New docs introducing the Analytics Header Filter policy: operation modes (allow/deny), independent requestHeadersToFilter and responseHeadersToFilter configurations, per-header parameter structure, system requirements (global analytics enabled, apply in API policy chain), API example, use cases, and notes on behavior and case-insensitive matching.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~2 minutes

Poem

🐰 I hopped through the docs with a bright little grin,

Tucking headers away where analytics begin,
Whitelist or blacklist — I sort with a cheer,
Case‑insensitive hops keep the data clear,
Tiny rabbit, tidy logs — hop into the clear!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description provides purpose and related issue but is incomplete, missing Goals, Approach, User stories, Documentation link, Automation tests, Security checks, Samples, Related PRs, and Test environment sections required by the template.	Complete the PR description by adding the remaining template sections: Goals, Approach, User stories, Documentation links, Automation tests, Security checks, Samples, Related PRs, and Test environment details.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding documentation for the analytics-header-filter policy, which matches the PR objectives and file additions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 4

🤖 Fix all issues with AI agents

In `@docs/ai-gateway/analytics/analytics-header-filter.md`:
- Around line 98-100: Remove the duplicate heredoc terminator in the example:
there's an extra "EOF" line that ends the block prematurely; edit the markdown
example in analytics-header-filter.md to keep only a single closing heredoc
terminator (remove the second "EOF") so the code block/example is not broken.
- Around line 58-60: The example curl in analytics-header-filter.md uses a
real-looking Basic auth value ("Authorization: Basic YWRtaW46YWRtaW4=") which
decodes to admin:admin; replace that header with a clear placeholder instead
(e.g., "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" or "Authorization:
Basic <username:password encoded>") so the example in the docs does not contain
real credentials; update the curl example lines with the placeholder token
wherever the Authorization header appears.
- Around line 113-118: The Notes are incorrect about empty `headers` behavior;
update the analytics-header-filter documentation so the `headers` array note
reflects the actual implementation: when `headers` is an empty array the
original headers are returned regardless of the `operation` value (`"allow"` or
`"deny"`). Amend the bullet that currently says empty `"allow"` yields no
headers to explicitly state that an empty `headers` list results in no filtering
and preserves original headers for both `allow` and `deny`, and keep the rest of
the `operation`/`headers` descriptions unchanged.

In `@docs/gateway/analytics/analytics-header-filter.md`:
- Around line 104-109: Update the third bullet under "Notes" to reflect actual
behavior: the `headers` array is required but can be empty, and when it is empty
the implementation returns the original (all) headers regardless of the
`operation` value; thus an empty array results in all headers being included for
both `"allow"` and `"deny"` modes. Mention that header name matching remains
case-insensitive and that `operation` must be `"allow"` or `"deny"`, but clarify
the empty-list fallback as described above to align docs with the
implementation.