networking: add connection backoff config options

[eschabell]

Adopts and rebases #491 onto master. Original author: @c445 (commit signoff preserved).

Closes #491.

Summary by CodeRabbit

• Documentation
  • Added documentation for new networking configuration properties enabling control over connection backoff behavior after failed connections.
  • Enhanced TCP keepalive behavior documentation with clarified explanations of connection timeout handling and closure mechanisms.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds documentation for two network backoff configuration properties: net.initial_backoff (backoff period after first connection failure) and net.max_backoff (maximum connection backoff period) to the networking configuration table. The TCP output example explanation is also reflowed for clarity regarding keepalive timeout behavior.

Changes

Network Backoff Configuration Documentation

Layer / File(s)	Summary
Network backoff configuration options and example administration/networking.md	Added net.initial_backoff and net.max_backoff configuration properties to the networking table. Reflowed the TCP output example explanation regarding net.keepalive and net.keepalive_idle_timeout connection closure behavior.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 With whiskers twitched, I document with care,
Two backoff options, floating in the air!
Connection retries, so gentle and so fine,
The networking docs now sparkly shine!
hop hop ✨

🚥 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 clearly and concisely describes the main change: adding connection backoff configuration options to networking documentation.
Linked Issues check	✅ Passed	The PR adds the two backoff config options (net.initial_backoff and net.max_backoff) to the networking documentation as required by issue #491.
Out of Scope Changes check	✅ Passed	All changes are directly related to documenting the connection backoff configuration options specified in issue #491; no out-of-scope modifications 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]

Actionable comments posted: 1

🧹 Nitpick comments (2)

administration/networking.md (2)

106-111: 💤 Low value

Consider demonstrating the new backoff options in the example.

The example showcases several networking options but doesn't include the newly documented net.initial_backoff and net.max_backoff properties. Adding them would help users understand their usage.

💡 Example with backoff options

For YAML format:

       net.keepalive: true
       net.keepalive_idle_timeout: 10s
+      net.initial_backoff: 1s
+      net.max_backoff: 30s

For conf format:

   net.keepalive               true
   net.keepalive_idle_timeout  10s
+  net.initial_backoff         1s
+  net.max_backoff             30s

Also applies to: 132-137

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@administration/networking.md` around lines 106 - 111, The example networking
block omits the new backoff settings; add net.initial_backoff and
net.max_backoff to the sample config so users see how to configure backoff
behavior (e.g., set net.initial_backoff and net.max_backoff alongside
net.connect_timeout, net.keepalive, net.keepalive_idle_timeout) and mirror the
same additions in the other example block referenced (the section around the
later 132-137 lines) so both examples demonstrate the new options consistently.

---

63-63: ⚡ Quick win

Consider enhancing the descriptions with backoff algorithm details.

The current descriptions are functional but could be more helpful by explaining:

• The backoff algorithm (exponential, linear, etc.)
• What happens when both values are 0 (the default) - is backoff disabled?
• How net.initial_backoff and net.max_backoff interact

📝 Example of more detailed descriptions

-| `net.initial_backoff`           | Backoff period in seconds after the first connection failure.                                                      | `0`     |
+| `net.initial_backoff`           | Initial backoff period in seconds after the first connection failure. When set to `0`, backoff is disabled. Used as the starting point for exponential backoff calculations.                                                      | `0`     |

-| `net.max_backoff`               | Maximum connection backoff period in seconds.                                                                      | `0`     |
+| `net.max_backoff`               | Maximum connection backoff period in seconds. Caps the exponential backoff to prevent excessively long wait times. When set to `0`, backoff is disabled.                                                                      | `0`     |

Also applies to: 72-72

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@administration/networking.md` at line 63, Update the documentation entries
for the net.initial_backoff and net.max_backoff settings to describe the backoff
algorithm and interaction: state whether the implementation uses exponential
(e.g., multiply by a factor per retry) or linear backoff, explain how
initial_backoff is the base delay and max_backoff caps the delay, specify
behavior when both are 0 (e.g., backoff disabled or immediate retries), and
include an example sequence (e.g., 1s -> 2s -> 4s -> ... capped at max) so
readers can see how values interact; update the description lines for
`net.initial_backoff` and `net.max_backoff` accordingly.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@administration/networking.md`:
- Line 63: The docs currently reference non-existent Fluent Bit options
`net.initial_backoff` and `net.max_backoff`; update the entries that mention
those keys (the lines referencing `net.initial_backoff` and `net.max_backoff`)
to use the actual Fluent Bit `[SERVICE]` options `scheduler.base` and
`scheduler.cap` (adjust descriptions to mention backoff base and cap in seconds
and set the correct default values), or alternatively note that these names are
only valid after an upstream change and should be removed until that
implementation is merged/released; ensure the text and defaults formerly under
`net.initial_backoff`/`net.max_backoff` are moved to the
`scheduler.base`/`scheduler.cap` entries and that any examples or semantic
descriptions match Fluent Bit’s scheduler semantics.

---

Nitpick comments:
In `@administration/networking.md`:
- Around line 106-111: The example networking block omits the new backoff
settings; add net.initial_backoff and net.max_backoff to the sample config so
users see how to configure backoff behavior (e.g., set net.initial_backoff and
net.max_backoff alongside net.connect_timeout, net.keepalive,
net.keepalive_idle_timeout) and mirror the same additions in the other example
block referenced (the section around the later 132-137 lines) so both examples
demonstrate the new options consistently.
- Line 63: Update the documentation entries for the net.initial_backoff and
net.max_backoff settings to describe the backoff algorithm and interaction:
state whether the implementation uses exponential (e.g., multiply by a factor
per retry) or linear backoff, explain how initial_backoff is the base delay and
max_backoff caps the delay, specify behavior when both are 0 (e.g., backoff
disabled or immediate retries), and include an example sequence (e.g., 1s -> 2s
-> 4s -> ... capped at max) so readers can see how values interact; update the
description lines for `net.initial_backoff` and `net.max_backoff` accordingly.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b1d08ccc-c832-4ac0-9f44-ec72b8c45b46

📥 Commits

Reviewing files that changed from the base of the PR and between 82ab6af and 2e4409e.

📒 Files selected for processing (1)

• administration/networking.md

[eschabell]

@kabakaev please feel free to review this new doc PR for your code PR fluent/fluent-bit#3191