docs: installation: upgrade-notes: add v5.0 notes, fix spelling suggestion

[eschabell]

• Add v5.0 section: hot_reloaded_times metric type change (gauge to counter)
• Add v5.0 section: emitter backpressure auto-enabled with filesystem storage
• Replace "stringified" with "string-encoded" in v1.2 Kubernetes filter note

Fixes #2527

Summary by CodeRabbit

Documentation

• Added Fluent Bit v5.0 upgrade notes documenting critical compatibility changes for metric types and pipeline storage behavior
• Detailed automatic storage pause configuration for emitter-backed pipelines using filesystem storage
• Updated existing compatibility guidance for improved clarity

[coderabbitai]

📝 Walkthrough

Walkthrough

Added a new Fluent Bit v5.0 upgrade notes section documenting two breaking changes: the internal metric fluentbit_hot_reloaded_times transitioning from gauge to counter, and automatic enablement of storage.pause_on_chunks_overlimit for emitter-backed pipelines using filesystem storage. Also updated terminology in existing v4.2 note.

Changes

Cohort / File(s)	Summary
Upgrade Notes Documentation installation/upgrade-notes.md	Added v5.0 section with two compatibility notes: (1) fluentbit_hot_reloaded_times metric type change from gauge to counter requiring PromQL function updates, and (2) emitter-backed pipeline storage behavior change with automatic storage.pause_on_chunks_overlimit enablement. Updated v4.2 Kubernetes filter note terminology from "stringified" to "string-encoded".

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• docs: monitoring: fix hot_reloaded_times metric type #2383: Documents the same code-level change of fluentbit_hot_reloaded_times metric transitioning from gauge to counter.
• docs: pipeline: buffering: general doc updates and cleanup #2517: Modifies documentation around pipeline storage configuration and storage.max_chunks_up setting referenced in the emitter pipeline behavior note.
• docs: administration: monitoring: fix fluentbit_hot_reloaded_times metric type and unit #2492: Documents the fluentbit_hot_reloaded_times gauge-to-counter metric change with monitoring implications.

Suggested reviewers

• patrick-stephens

Poem

🐰 A rabbit hops through version lanes,
New v5.0 notes ease upgrade pains!
Metrics transform, storage behaves anew,
With careful docs, users know what to do! 📝✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: adding v5.0 upgrade notes and fixing a spelling/terminology suggestion in the documentation.
Linked Issues check	✅ Passed	The PR addresses issue #2527 by providing upgrade documentation for v5.0, including metric type changes and behavior modifications relevant to users upgrading from 4.x.
Out of Scope Changes check	✅ Passed	All changes are scoped to upgrade documentation: v5.0 notes (metric change, emitter backpressure) and a terminology clarification in existing v4.2 notes. No unrelated changes detected.
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.}

✨ 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 (3)

installation/upgrade-notes.md (3)

25-25: Clarify configuration syntax and placement.

The instruction "explicitly set storage.pause_on_chunks_overlimit off" could be clearer about:

1. The value off should be in backticks for consistency
2. Where this setting should be placed (on the input plugin configuration)

📝 Suggested improvement for clarity

-If you rely on the previous unlimited accumulation behavior, explicitly set `storage.pause_on_chunks_overlimit off` on the relevant input. Otherwise, review your `storage.max_chunks_up` value to ensure it's tuned for your expected throughput.
+If you rely on the previous unlimited accumulation behavior, explicitly set `storage.pause_on_chunks_overlimit` to `off` on the relevant input plugin. Otherwise, review your `storage.max_chunks_up` value to ensure it's tuned for your expected throughput.

🤖 Prompt for AI Agents

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

In `@installation/upgrade-notes.md` at line 25, Clarify that the setting key is
`storage.pause_on_chunks_overlimit` and the literal value should be written as
`off` (in backticks) and explicitly state that this line belongs inside the
relevant input plugin block (i.e., add it to the input plugin configuration for
the data source that previously relied on unlimited accumulation); also mention
that `storage.max_chunks_up` is the global/related config to review and tune for
expected throughput.

---

21-21: Awkward phrasing: "automatically enables".

The phrase "now automatically enables storage.pause_on_chunks_overlimit" is grammatically awkward. The plugin is the subject, but the phrasing makes it unclear whether the plugin actively enables something or has a setting automatically enabled.

✍️ Suggested rephasing for clarity

-The internal emitter plugin, used by filters such as `rewrite_tag`, now automatically enables `storage.pause_on_chunks_overlimit` when filesystem storage is in use and that option hasn't been explicitly configured.
+The internal emitter plugin, used by filters such as `rewrite_tag`, now has `storage.pause_on_chunks_overlimit` automatically enabled when filesystem storage is in use and that option hasn't been explicitly configured.

or alternatively:

-The internal emitter plugin, used by filters such as `rewrite_tag`, now automatically enables `storage.pause_on_chunks_overlimit` when filesystem storage is in use and that option hasn't been explicitly configured.
+The internal emitter plugin, used by filters such as `rewrite_tag`, now defaults to `storage.pause_on_chunks_overlimit on` when filesystem storage is in use and that option hasn't been explicitly configured.

🤖 Prompt for AI Agents

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

In `@installation/upgrade-notes.md` at line 21, Rephrase the sentence about the
internal emitter plugin to remove the awkward active phrasing "automatically
enables" and make the behavior clear; for example, say that the internal emitter
plugin (used by filters such as `rewrite_tag`) will cause
`storage.pause_on_chunks_overlimit` to be enabled when filesystem storage is
detected and that option has not been explicitly set, or say that the plugin now
defaults `storage.pause_on_chunks_overlimit` to enabled under those conditions —
ensure you reference `internal emitter plugin`, `rewrite_tag`,
`storage.pause_on_chunks_overlimit`, and "filesystem storage" in the new
sentence for clarity.

---

19-25: Update pipeline/buffering.md to document automatic emitter behavior with storage.pause_on_chunks_overlimit.

The upgrade notes document that emitters automatically enable storage.pause_on_chunks_overlimit when filesystem storage is in use, but pipeline/buffering.md:140 shows the default as off without mentioning this automatic enablement for emitter-backed pipelines. Add a note to the storage.pause_on_chunks_overlimit configuration description to clarify that this setting is automatically enabled for emitters with filesystem storage unless explicitly set otherwise.

🤖 Prompt for AI Agents

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

In `@installation/upgrade-notes.md` around lines 19 - 25, Update the
storage.pause_on_chunks_overlimit description in pipeline/buffering.md to note
that emitter-backed pipelines (e.g., the internal emitter used by filters like
rewrite_tag) automatically enable storage.pause_on_chunks_overlimit when
filesystem storage is detected unless the option is explicitly set; keep the
default shown as off but add a clarifying sentence referencing "emitter"
behavior and the exception for explicit configuration so readers know to set
storage.pause_on_chunks_overlimit off if they want the old unlimited
accumulation behavior.

🤖 Prompt for all review comments with AI agents

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

Nitpick comments:
In `@installation/upgrade-notes.md`:
- Line 25: Clarify that the setting key is `storage.pause_on_chunks_overlimit`
and the literal value should be written as `off` (in backticks) and explicitly
state that this line belongs inside the relevant input plugin block (i.e., add
it to the input plugin configuration for the data source that previously relied
on unlimited accumulation); also mention that `storage.max_chunks_up` is the
global/related config to review and tune for expected throughput.
- Line 21: Rephrase the sentence about the internal emitter plugin to remove the
awkward active phrasing "automatically enables" and make the behavior clear; for
example, say that the internal emitter plugin (used by filters such as
`rewrite_tag`) will cause `storage.pause_on_chunks_overlimit` to be enabled when
filesystem storage is detected and that option has not been explicitly set, or
say that the plugin now defaults `storage.pause_on_chunks_overlimit` to enabled
under those conditions — ensure you reference `internal emitter plugin`,
`rewrite_tag`, `storage.pause_on_chunks_overlimit`, and "filesystem storage" in
the new sentence for clarity.
- Around line 19-25: Update the storage.pause_on_chunks_overlimit description in
pipeline/buffering.md to note that emitter-backed pipelines (e.g., the internal
emitter used by filters like rewrite_tag) automatically enable
storage.pause_on_chunks_overlimit when filesystem storage is detected unless the
option is explicitly set; keep the default shown as off but add a clarifying
sentence referencing "emitter" behavior and the exception for explicit
configuration so readers know to set storage.pause_on_chunks_overlimit off if
they want the old unlimited accumulation behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5c42cc08-3dd5-4ab8-8c52-200f41bdf011

📥 Commits

Reviewing files that changed from the base of the PR and between c7214d5 and ff3e3d4.

📒 Files selected for processing (1)

• installation/upgrade-notes.md

[eschabell]

@patrick-stephens ready for review!