Skip to content

docs: add rate limiting guide#7659

Open
CharlieTLe wants to merge 2 commits into
cortexproject:masterfrom
CharlieTLe:docs/rate-limiting-guide
Open

docs: add rate limiting guide#7659
CharlieTLe wants to merge 2 commits into
cortexproject:masterfrom
CharlieTLe:docs/rate-limiting-guide

Conversation

@CharlieTLe

Copy link
Copy Markdown
Member

Summary

Adds a new guide at docs/guides/rate-limiting.md documenting the write-path rate limiters, which were previously only partially documented in docs/configuration/arguments.md and the auto-generated config reference.

The new page covers:

  • Per-tenant ingestion limiter — token-bucket semantics, what totalN counts (samples + exemplars + metadata), and the 10s recheck for runtime overrides.
  • local vs global strategy — including the load-balancing assumption and the fact that ingestion_burst_size is not divided by N under the global strategy.
  • Sizing guidance — burst must be ≥ the largest expected single push.
  • Native histogram limiter — separate token bucket, applied after the main limiter, so a histogram-only rejection still ingests floats / exemplars / metadata.
  • Per-instance limits-distributor.instance-limits.max-ingestion-rate and -ingester.instance-limits.max-ingestion-rate (EWMA-based, HTTP 503 / gRPC error).
  • Errors and observability — the exact response codes and messages, retry_on_http_429 behavior, and the relevant cortex_distributor_*, cortex_discarded_*, and cortex_overrides metrics.

Also adds a cross-link to the new guide from the per-tenant limits section in docs/configuration/arguments.md.

Docs-only change — no CHANGELOG entry.

Test plan

  • Render the docs locally and verify the new page appears under Guides and that the cross-link from arguments.md resolves.
  • Spot-check internal links: ./overrides.md, ./overrides-exporter.md, ../configuration/arguments.md.

Add a new guide explaining the write-path rate limiters: the per-tenant
token bucket (ingestion_rate / ingestion_burst_size) including the
local vs. global strategy, the separate native histogram limiter, and
the per-instance distributor and ingester caps. Covers configuration,
error responses, and relevant metrics.

Also cross-link to the new guide from the per-tenant limits section in
docs/configuration/arguments.md.

Signed-off-by: Charlie Le <charlie_le@apple.com>
@CharlieTLe CharlieTLe marked this pull request as ready for review June 30, 2026 23:03

@SungJin1212 SungJin1212 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks!

@dosubot dosubot Bot added the lgtm This PR has been approved by a maintainer label Jul 1, 2026
Comment thread docs/guides/rate-limiting.md Outdated
Co-authored-by: SungJin1212 <tjdwls1201@gmail.com>
Signed-off-by: Charlie Le <charlie_le@apple.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component/documentation lgtm This PR has been approved by a maintainer size/L

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants