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 docs for two new Tail input options: keeping file handles open and configuring file-status check intervals, with notes on effects for cloud and SMB/Samba backends.
  • New SMB/Samba tailing section with behavior guidance and example configs.
  • Expanded character-encoding conversion guidance with more examples, usage scenarios, and supported encodings details.

_{✏️ 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 behavior notes and example Fluent Bit YAML/conf configs, and expands the Character Encoding Conversion guidance with examples and encoding details.

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 describing behavior and implications, with example Fluent Bit YAML and conf configurations; expanded Character Encoding Conversion section with additional guidance, examples, and encoding details.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

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

Poem

🐇 I hopped through lines of tail and file,

Kept a handle close or let it roam a while,
Counting nanos in a patient beat,
SMB corners swept tidy and neat,
A rabbit's note — docs polished with a smile.

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 concisely summarizes the main changes: two new configuration options (keep_file_handle and fstat_interval_nsec) added to the Tail input documentation.
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 96b0928 and ae0b9d1.

📒 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

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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