Skip to content

docs(dogstatsd): document dogstatsd_mem_based_rate_limiter.* as architectural divergence #1775

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jszwedko wants to merge 5 commits into
base: main
Choose a base branch
from
Open

docs(dogstatsd): document dogstatsd_mem_based_rate_limiter.* as architectural divergence #1775

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ee2000b
docs(dogstatsd): document dogstatsd_mem_based_rate_limiter.* as archi…
jszwedko May 29, 2026
8d45b08
docs(dogstatsd): fix table column alignment in mem_based_rate_limiter…
jszwedko May 29, 2026
b92351e
docs(dogstatsd): fix trailing whitespace in mem_based_rate_limiter ta…
jszwedko May 29, 2026
4d62df9
docs(dogstatsd): remove hardcoded key count from rate limiter explana…
jszwedko May 29, 2026
ddba05e
Merge origin/main: resolve conflict in dogstatsd.md Last updated date
jszwedko May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions docs/agent-data-plane/configuration/dogstatsd.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Configuring DogStatsD on Agent Data Plane

<!-- Last updated: 2026-05-28 -->
<!-- Last updated: 2026-05-29 -->

The DogStatsD implementation on ADP has been redesigned in Rust for better resource guarantees and
efficiency. Because the architecture is different from the original implementation, certain
Expand Down Expand Up @@ -46,7 +46,7 @@ architecture is fundamentally different or the feature is platform-specific.
| Config Key | Description | Reason |
| ---------------------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
| `dogstatsd_host_socket_path` | Host UDS socket dir for DSD | Not read by DSD server; admission controller only |
| `dogstatsd_mem_based_rate_limiter.enabled` | Enable memory rate limiter | Go GC specific; use `memory_limit` |
| `dogstatsd_mem_based_rate_limiter.*` | Memory-based rate limiter | Go GC–specific; ADP uses `memory_limit` (see below) |
| `dogstatsd_no_aggregation_pipeline_batch_size` | No-aggregation pipeline batch size | Fixed in ADP topology |
| `dogstatsd_packet_buffer_flush_timeout` | Packet buffer flush timeout | ADP decodes inline |
| `dogstatsd_packet_buffer_size` | Datagrams per packet buffer | ADP decodes inline |
Expand All @@ -57,6 +57,29 @@ architecture is fundamentally different or the feature is platform-specific.
| `dogstatsd_workers_count` | Number of DSD processing workers | ADP uses async tasks |
| `use_dogstatsd` | Master DogStatsD enable toggle | Core Agent evaluates and sets `data_plane.dogstatsd.enabled` |

### Memory-based rate limiter (`dogstatsd_mem_based_rate_limiter.*`)

The core agent exposes configuration under this prefix to apply backpressure when the Go process
approaches its memory limit. They work by manipulating Go's garbage collector
(`debug.SetGCPercent`, `debug.FreeOSMemory`), allocating a large heap ballast to adjust GC
heuristics, and blocking goroutines to slow packet ingestion. None of these mechanisms have
an equivalent in Rust, and ADP does not use a Go runtime.

ADP takes a different approach to the same problem:

- **Static bounds**: components declare their memory footprint at startup via `MemoryBounds`.
ADP refuses to start if declared bounds exceed the configured `memory_limit`, preventing
over-commitment before any traffic arrives.
- **Dynamic limiting**: a `MemoryLimiter` polls the process RSS every 250 ms. When usage
exceeds 95 % of the effective limit it applies proportional async backpressure (1–25 ms)
to ingestion tasks.
- **Structural backpressure**: bounded channels between components provide back-pressure
independently of memory monitoring.

To set a process memory limit in ADP, use `memory_limit` (bytes). The `memory_slop_factor`
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector Bot May 29, 2026

Choose a reason for hiding this comment

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

P2 Badge Document the required memory mode

When a user follows this replacement guidance and only sets memory_limit, ADP does not actually enforce the static bounds or start the RSS-based limiter: memory_mode defaults to Disabled and initialize_memory_bounds returns a no-op limiter in that branch (lib/saluki-app/src/memory.rs lines 91-93 and 157-177). This section should mention that the described refusal/backpressure behavior requires memory_mode: strict or permissive (and enable_global_limiter for dynamic backpressure), otherwise the ignored DogStatsD limiter keys are not replaced by active memory limiting.

Useful? React with 👍 / 👎.

setting reserves a headroom fraction to account for allocations not tracked by ADP's internal
accounting. All 11 `dogstatsd_mem_based_rate_limiter.*` keys are ignored by ADP.

## Behavioral Differences

<!-- section:behavioral-differences -->
Expand Down
Loading