docs: admin: Storage backlog mem limit fixes

[eschabell]

docs: administration: backpressure: separate storage.backlog.mem_limit from storage.max_chunks_up

  - Rename the heading to "Set storage.max_chunks_up in global settings"
    and rewrite the paragraph to describe only that setting
  - Add a new "Tune storage.backlog.mem_limit for the backlog plugin"
    subsection clarifying its actual scope
  - Update the storage.pause_on_chunks_overlimit subsection to reference
    storage.max_chunks_up only

docs: administration: yaml: service-section: fix storage.backlog.mem_limit description

  - Rewrite the description to scope the setting to the storage_backlog
    input plugin
  - Note explicitly that it doesn't cap memory used by other filesystem-
    buffering inputs

Fixes #2555.

Summary by CodeRabbit

Release Notes

• Documentation
  • Clarified storage backpressure configuration guidance for better understanding of memory management behavior
  • Improved documentation of filesystem-buffering settings and how storage limits apply across different input plugins
  • Enhanced explanations of storage.max_chunks_up and storage.backlog.mem_limit configuration options

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation clarifies that storage.backlog.mem_limit applies exclusively to the storage_backlog plugin's backlog chunk promotion, not as a global memory cap for all filesystem-buffering inputs. Updates emphasize storage.max_chunks_up as the primary global memory limit controlling regular input plugin memory usage.

Changes

Cohort / File(s)	Summary
Backpressure Documentation administration/backpressure.md	Restructures guidance to isolate storage.backlog.mem_limit as plugin-specific; clarifies storage.max_chunks_up as sole global memory cap; updates storage.pause_on_chunks_overlimit behavior description.
Service Configuration Documentation administration/configuring-fluent-bit/yaml/service-section.md	Narrows storage.backlog.mem_limit description from general memory allocation statement to specific storage_backlog plugin behavior; adds clarification that setting does not constrain other input plugins.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• #2324 — Modifies the same backpressure and storage configuration documentation sections to rework buffering behavior descriptions.

Suggested labels

4.2.3

Suggested reviewers

• esmerel
• patrick-stephens

Poem

🐰 Hops through the docs with careful paws,
Clarifying limits, without a pause,
Storage backlogs now understood,
Each plugin's role, as it should! 📚✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR documentation changes directly address issue #2555 by clarifying that storage.backlog.mem_limit applies only to the storage_backlog plugin, not all filesystem-buffered inputs, and separating it from the global storage.max_chunks_up setting.
Out of Scope Changes check	✅ Passed	All changes are documentation updates focused on clarifying storage.backlog.mem_limit and storage.max_chunks_up behavior, which directly aligns with the scope defined in issue #2555.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title clearly summarizes the main change: documentation clarification of storage.backlog.mem_limit scope and its distinction from storage.max_chunks_up, which is the primary focus across both modified files.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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]

🧹 Nitpick comments (2)

administration/configuring-fluent-bit/yaml/service-section.md (1)

48-48: ⚡ Quick win

Consider rephrasing for improved clarity.

The sentence "While the up chunks owned by storage_backlog consume less memory than this limit, Fluent Bit continues to promote additional backlog chunks" uses a structure that could be clearer. The word "While" typically introduces a contrast, but here it describes a condition for continuation.

Consider rephrasing to make the causal relationship more explicit:

"Fluent Bit continues to promote additional backlog chunks as long as the up chunks owned by storage_backlog consume less memory than this limit."

This alternative phrasing more clearly conveys that promotion continues because (or as long as) memory consumption is below the limit.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@administration/configuring-fluent-bit/yaml/service-section.md` at line 48,
Update the wording for the storage.backlog.mem_limit description: replace the
sentence beginning "While the up chunks owned by `storage_backlog` consume less
memory than this limit, Fluent Bit continues to promote additional backlog
chunks" with a clearer causal phrasing such as "Fluent Bit continues to promote
additional backlog chunks as long as the up chunks owned by `storage_backlog`
consume less memory than this limit," ensuring you keep references to
`storage.backlog.mem_limit`, `storage_backlog`, and Fluent Bit intact.

administration/backpressure.md (1)

73-73: ⚡ Quick win

Consider rephrasing for improved clarity.

The sentence "While the up chunks owned by storage_backlog consume less memory than this limit, Fluent Bit continues to promote additional backlog chunks" uses the same awkward phrasing as in service-section.md.

For consistency and clarity across both files, consider the same rephrasing:

"Fluent Bit continues to promote additional backlog chunks as long as the up chunks owned by storage_backlog consume less memory than this limit."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@administration/backpressure.md` at line 73, Rephrase the awkward sentence
about promotion logic to match the suggested wording: replace the sentence that
currently reads "While the up chunks owned by `storage_backlog` consume less
memory than this limit, Fluent Bit continues to promote additional backlog
chunks" with "Fluent Bit continues to promote additional backlog chunks as long
as the up chunks owned by `storage_backlog` consume less memory than this
limit." Keep references to `storage.backlog.mem_limit` and the `storage_backlog`
input plugin intact for clarity and consistency with service-section.md.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@administration/backpressure.md`:
- Line 73: Rephrase the awkward sentence about promotion logic to match the
suggested wording: replace the sentence that currently reads "While the up
chunks owned by `storage_backlog` consume less memory than this limit, Fluent
Bit continues to promote additional backlog chunks" with "Fluent Bit continues
to promote additional backlog chunks as long as the up chunks owned by
`storage_backlog` consume less memory than this limit." Keep references to
`storage.backlog.mem_limit` and the `storage_backlog` input plugin intact for
clarity and consistency with service-section.md.

In `@administration/configuring-fluent-bit/yaml/service-section.md`:
- Line 48: Update the wording for the storage.backlog.mem_limit description:
replace the sentence beginning "While the up chunks owned by `storage_backlog`
consume less memory than this limit, Fluent Bit continues to promote additional
backlog chunks" with a clearer causal phrasing such as "Fluent Bit continues to
promote additional backlog chunks as long as the up chunks owned by
`storage_backlog` consume less memory than this limit," ensuring you keep
references to `storage.backlog.mem_limit`, `storage_backlog`, and Fluent Bit
intact.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 890c2694-7cab-4e04-890c-7c1f1c5116ba

📥 Commits

Reviewing files that changed from the base of the PR and between 53a72bd and 4f2bc75.

📒 Files selected for processing (2)

• administration/backpressure.md
• administration/configuring-fluent-bit/yaml/service-section.md