Skip to content

in_tail: Add opt-in directory watching for earlier file discovery - #5528

Draft
ashie wants to merge 5 commits into
masterfrom
in-tail-dir-watcher
Draft

ashie wants to merge 5 commits into
masterfrom
in-tail-dir-watcher

Conversation

@ashie

@ashie ashie commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

Which issue(s) this PR fixes:
Fixes #2985

What this PR does / why we need it:

(This PR depends on #5527 and includes its commits.)

Currently, in_tail discovers files at previously unwatched paths through
periodic checks controlled by refresh_interval (60 seconds by default).

This PR adds opt-in enable_dir_watcher to check for new files when
directories derived from the configured paths change, without waiting
for the next periodic check. Multiple change notifications are grouped
into a single refresh.

  • Reuse Coolio::StatWatcher, without adding runtime dependencies.
  • Keep periodic refreshes as a fallback for missed changes and unwatched
    directories.
  • Handle wildcard and recursive patterns, brace alternatives,
    time-dependent paths, and symbolic links.
  • Add dir_watcher_limit (default: 100, positive integer). When candidates
    exceed the limit, rotate the watched subset on periodic refreshes.
    This limits active directory watchers, not candidate exploration.

The option remains disabled by default to preserve existing discovery
timing. Rotated files matching path may also be discovered earlier,
including cases where existing refresh behavior rereads them.

Detection latency depends on the platform and filesystem: libev uses
inotify where available and falls back to stat polling.

Docs Changes:

The in_tail documentation needs entries for:

  • enable_dir_watcher (default: false)
  • dir_watcher_limit (default: 100)

It should also describe platform-dependent detection latency, periodic
refresh fallback, and earlier discovery of matching rotated files.

Release Note:

in_tail: Add opt-in directory watching for earlier discovery of new files,
with a configurable watcher limit and periodic rotation of watched
directories when the limit is exceeded.

Assisted-by: LLM Qwen3.8-Flash-Next
Assisted-by: LLM GPT-6.1 Sol (OpenAI)

ashie added 5 commits October 9, 2026 15:56
Signed-off-by: Takuro Ashie <ashie@clear-code.com>
Signed-off-by: Takuro Ashie <ashie@clear-code.com>
Currently, in_tail checks for files at previously unwatched paths every
refresh_interval (60 seconds by default).

Add opt-in enable_dir_watcher to watch the directories of the configured
paths and check for new files when those directories change, without
waiting for the next periodic check. Group multiple directory changes
into a single refresh of the watched file list.

Keep periodic checks as a fallback for directory changes that are not
detected, and limit the number of watched directories.

Keep the option disabled by default to preserve existing discovery
timing. Rotated files that match path can also be discovered earlier,
including cases where the existing refresh behavior rereads them.

Fixes #2985

Signed-off-by: Takuro Ashie <ashie@clear-code.com>
Assisted-by: LLM GPT-6.1 Sol (OpenAI)
Add dir_watcher_limit with a default of 100 and require a positive value.
When candidates exceed the limit, rotate a window of the interleaved
candidates on periodic refreshes. Directory changes keep the current
window, while periodic requests merged into a pending refresh still
advance it.

Keep the starting directory when candidates change, and detach watchers
outside the new window before attaching replacements to avoid exceeding
the limit during rotation. Candidate exploration remains unrestricted.

Assisted-by: LLM GPT-6.1 Sol (OpenAI)
Signed-off-by: Takuro Ashie <ashie@clear-code.com>
Keep unresolved directory prefixes during traversal so a symbolic link
followed by .. is interpreted like file lookup on each platform.
Canonicalize watcher candidates only after traversal, normalizing Windows
relative components before resolving symbolic links.

Test both glob and literal paths with files on either side of the link
to distinguish Windows and Unix lookup behavior.

Assisted-by: LLM GPT-6.1 Sol (OpenAI)
Signed-off-by: Takuro Ashie <ashie@clear-code.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use notification mechanisms for watching new files in tail plugin instead of refresh_interval

1 participant