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 user-facing docs for two new Tail options: configurable file-status check interval and optional persistent file handles, with guidance and examples for cloud and SMB/Samba mounts (impacts on rotation detection and deletion).
• Style
  • Updated style rules to exempt CSI and SMB and added a heading exception for "Tailing files from SMB/Samba".

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds two Tail input options (fstat_interval_nsec, keep_file_handle) and a new "Tailing files from SMB/Samba" section (behavior, caveats, and examples). Also updates Vale style exceptions to include CSI and SMB. The SMB/Samba section is duplicated in the document.

Changes

Cohort / File(s)	Summary
Tail input documentation pipeline/inputs/tail.md	Added fstat_interval_nsec (accepts time units → stored as ns) and keep_file_handle options with descriptions and defaults; introduced "Tailing files from SMB/Samba" section with caveats and Fluent Bit YAML/conf examples; duplicated the SMB/Samba section.
Vale style rules vale-styles/FluentBit/Acronyms.yml, vale-styles/FluentBit/Headings.yml	Added CSI and SMB to acronym exceptions and added Tailing files from SMB/Samba to heading exceptions to suppress style warnings.

Sequence Diagram(s)

(Skipped — changes are documentation and style updates, not multi-component control flow.)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Vale/general: various page updates to reduce messages #2167 — modifies Vale style exception files in a similar way (acronyms/heading exceptions).

Suggested labels

4.2

Suggested reviewers

• alexakreizinger

Poem

🐇 I hopped through docs where tailing grows,

Counting nanos while the SMB wind blows,
I kept a handle, watched rotations stray,
Examples handy to show the way,
A rabbit smiles and bounds away.

🚥 Pre-merge checks | ✅ 3

✅ 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 change: adding two new configuration options (keep_file_handle and fstat_interval_nsec) to the tail input.
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
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

---

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!)

[eschabell]

@david-garcia-garcia failing on some lint issues... if you can take a look so this is ready when the code PR merges?

[alexakreizinger]

@eschabell I just caught/fixed the failing check, should be able to merge now :)

[eschabell]

@david-garcia-garcia linting errors need to be addressed before review please.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@vale-styles/FluentBit/Headings.yml`:
- Around line 145-148: The list item "Tailing files from SMB/Samba" is misplaced
in the S-section; remove the "Tailing files from SMB/Samba" entry between "SQL"
and "SSL" and insert it into the T-section (for example, directly after "TCP")
so the overall list remains alphabetically ordered; ensure you update only the
list ordering and preserve the exact text "Tailing files from SMB/Samba".

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Tailing files from SMB/Samba is out of alphabetical order.

SMB on line 145 is correctly placed. However, Tailing files from SMB/Samba (starting with "T") is inserted between SQL and SSL, breaking the alphabetical ordering of the list. It should be moved to the T-section, e.g., after TCP (line 154).

Proposed fix

   - SMB
   - SQL
-  - Tailing files from SMB/Samba
   - SSL
   - SSM
   - StatsD
   - Studio
   - Sumo Logic
   - Tanzu
   - TCP
+  - Tailing files from SMB/Samba
   - Telemetry Pipeline

🤖 Prompt for AI Agents

In `@vale-styles/FluentBit/Headings.yml` around lines 145 - 148, The list item
"Tailing files from SMB/Samba" is misplaced in the S-section; remove the
"Tailing files from SMB/Samba" entry between "SQL" and "SSL" and insert it into
the T-section (for example, directly after "TCP") so the overall list remains
alphabetically ordered; ensure you update only the list ordering and preserve
the exact text "Tailing files from SMB/Samba".

[david-garcia-garcia]

@eschabell I have run vale locally to fix the issues, but I am getting unexpected results about errors with something not modified in this PR. Can the workflow be triggered again? Thanks.