tail: New keep_file_handle and fstat_interval_nsec options for tail i…

[david-garcia-garcia]

See fluent/fluent-bit#11151

Summary by CodeRabbit

• Documentation
  • Added documentation for two new Tail input configuration options controlling file-handle behavior and file-status check intervals, including implications for cloud and SMB backends.
  • Expanded SMB/Samba tailing guidance with behavior notes and example configurations.
  • Expanded character-encoding conversion guidance with additional examples, usage scenarios, and supported encodings reference.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

Updates Tail input documentation: adds keep_file_handle and fstat_interval_nsec options, introduces an SMB/SAMBA tailing section with examples, and expands the Character Encoding Conversion guidance with examples and encoding tables.

Changes

Cohort / File(s)	Summary
Tail input documentation pipeline/inputs/tail.md	Added keep_file_handle and fstat_interval_nsec configuration options and explanations; added an SMB/SAMBA tailing section with behavior notes and example Fluent Bit YAML/conf configs; expanded Character Encoding Conversion section with guidance, examples, and encoding tables.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

• Documentation-only changes; no code or API modifications.
• Focus review on clarity and accuracy of examples and encoding tables.

Poem

🐰 I hopped through docs to add a new trail,

keep the handle or let it set sail,
nanosecond checks to time every file,
SMB notes and encodings compiled,
A nibble of docs — precise, neat, and agile.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main changes: introducing two new configuration options (keep_file_handle and fstat_interval_nsec) for the tail input plugin.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f22a8d7 and 96b0928.

📒 Files selected for processing (1)

• pipeline/inputs/tail.md (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• pipeline/inputs/tail.md

---

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: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

pipeline/inputs/tail.md (1)

85-95: Remove duplicate hint box on Unicode.Encoding.

Lines 85-89 and 91-95 contain identical warning text about the Unicode.Encoding parameter. Delete the redundant section to avoid reader confusion.

{% endhint %}

-{% hint style="info" %}
-The `Unicode.Encoding` parameter is dependent on the `simdutf` library, which is itself dependent on C++ version 11 or later. In environments that use earlier versions of C++, the `Unicode.Encoding` parameter will fail.
-
-Additionally, the `auto` setting for `Unicode.Encoding` isn't supported in all cases, and can make mistakes when it tries to guess the correct encoding. For best results, use either the `UTF-16LE` or `UTF-16BE` setting if you know the encoding type of the target file.
-{% endhint %}

🧹 Nitpick comments (1)

pipeline/inputs/tail.md (1)

479-509: Align SMB/SAMBA section wording with configuration table for consistency.

Line 481 states that setting keep_file_handle to false "disables log rotation detection," but the configuration table (line 40) provides more nuanced guidance: "Rotation will be detected as a truncation, so some logs might be lost."

Clarify that rotation detection is modified, not entirely disabled, to set proper expectations for users.

Consider updating line 481 to:

-...Note that this disables log rotation detection.
+...Note that log rotation will be detected as a truncation event, which may result in some log loss.

This aligns with the more detailed explanation in the configuration table and provides users with a clearer understanding of the tradeoff.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2dee9d8 and f22a8d7.

📒 Files selected for processing (1)

• pipeline/inputs/tail.md (2 hunks)

🔇 Additional comments (2)

pipeline/inputs/tail.md (2)

40-41: Configuration parameters clearly documented with appropriate defaults.

The new keep_file_handle and fstat_interval_nsec parameters are well-described with clear guidance on tradeoffs (e.g., rotation detection implications, IOPS sensitivity). The placement in the table is appropriate, and defaults are specified.

---

511-595: Character Encoding Conversion section is well-structured and provides excellent guidance.

The expanded section clearly explains when and how to use encoding conversion, with good organization of encoding types and practical examples. The separation between Unicode.Encoding and Generic.Encoding use cases is helpful.

[alexakreizinger]

thanks for submitting a PR :)

I added a few suggestions based on our style guide, but let me know if I got anything wrong. (also, I believe that "Samba" should be a proper noun and not an acronym, but if that's not correct I can fix it!)