From 8825c508fd65488f8a51ce63f699e018d3f5a264 Mon Sep 17 00:00:00 2001 From: Hofi Date: Thu, 21 Aug 2025 12:22:16 +0200 Subject: [PATCH] file(): restored the legacy file() source options page and added a warning of its 'deprecation' at multiple places Signed-off-by: Hofi --- _data/link_aliases.yml | 3 ++ _data/navigation.yml | 12 +++-- .../doc/admin-guide/options/follow-method.md | 2 +- .../file-source-deprecation-warning.md | 3 ++ .../warnings/file-source-follow-warning.md | 3 +- .../020_File/000_File_source_options.md | 52 +++++++++++++++++++ ...> 001_Notes_on_reading_kernel_messages.md} | 0 .../060_Sources/020_File/README.md | 8 +-- 8 files changed, 72 insertions(+), 11 deletions(-) create mode 100644 _includes/doc/admin-guide/warnings/file-source-deprecation-warning.md create mode 100644 doc/_admin-guide/060_Sources/020_File/000_File_source_options.md rename doc/_admin-guide/060_Sources/020_File/{000_Notes_on_reading_kernel_messages.md => 001_Notes_on_reading_kernel_messages.md} (100%) diff --git a/_data/link_aliases.yml b/_data/link_aliases.yml index 5b5ed2f5..6cb8b5c4 100644 --- a/_data/link_aliases.yml +++ b/_data/link_aliases.yml @@ -165,6 +165,9 @@ adm-src-hypr: adm-src-macOS: aliases: [ "darwin-oslog()", "darwin-oslog-stream()" ] +adm-src-file-note: + aliases: [ "read kernel messages" ] + adm-dest-google-bq: aliases: [ "bigquery()" ] diff --git a/_data/navigation.yml b/_data/navigation.yml index e82b7a70..ad33bbdf 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -138,20 +138,20 @@ admin-guide-nav: subnav: - title: "internal() source options" url: /admin-guide/060_Sources/010_Internal/000_Internal_options - - title: "file (DEPRECATED)" + - title: "file" url: /admin-guide/060_Sources/020_File/README subnav: - title: "file() source options" url: /admin-guide/060_Sources/020_File/000_File_source_options - - title: "How file sources are followed" - url: /admin-guide/060_Sources/020_File/001_File_following - title: "Notes on reading kernel messages" - url: /admin-guide/060_Sources/020_File/002_Notes_on_reading_kernel_messages + url: /admin-guide/060_Sources/020_File/001_Notes_on_reading_kernel_messages - title: "wildcard-file" url: /admin-guide/060_Sources/021_Wildcard-file/README subnav: - title: "wildcard-file() source options" url: /admin-guide/060_Sources/021_Wildcard-file/000_Wildcard-file_options + - title: "How file sources are followed" + url: /admin-guide/060_Sources/021_Wildcard-file/001_File_following - title: "freebsd-audit" url: /admin-guide/060_Sources/030_Freebsd-audit/README subnav: @@ -403,7 +403,7 @@ admin-guide-nav: url: /admin-guide/070_Destinations/100_Kafka-c/001_Shifting_from_Java_to_C - title: "Flow control in {{ site.product.short_name }} and the Kafka client" url: /admin-guide/070_Destinations/100_Kafka-c/002_Flow_control - - title: "Options of the kafka() destination's C implementation" + - title: "Options of the kafka() destination" url: /admin-guide/070_Destinations/100_Kafka-c/003_Kafka-c_options - title: "Loggly" url: /admin-guide/070_Destinations/110_Loggly/README @@ -689,6 +689,8 @@ admin-guide-nav: url: /admin-guide/080_Log/030_Filters/005_Filter_functions/011_source - title: "tags()" url: /admin-guide/080_Log/030_Filters/005_Filter_functions/012_tags + - title: "blank()" + url: /admin-guide/080_Log/030_Filters/005_Filter_functions/013_blank - title: "Dropping messages" url: /admin-guide/080_Log/040_Dropping_messages - title: "Global options of {{ site.product.short_name }}" diff --git a/_includes/doc/admin-guide/options/follow-method.md b/_includes/doc/admin-guide/options/follow-method.md index abc815c7..154118ae 100644 --- a/_includes/doc/admin-guide/options/follow-method.md +++ b/_includes/doc/admin-guide/options/follow-method.md @@ -7,7 +7,7 @@ The default `legacy` mode preserves the pre-4.9 version file follow-mode behavior of {{ site.product.short_name }}, which is based on the value of follow-freq().\ The `poll` value forces {{ site.product.short_name }} to poll for file changes at the interval specified by the monitor-freq() option, even if a more efficient method (such as `inotify` or `kqueue`) is available.\ If `inotify` is selected and supported by the platform, {{ site.product.short_name }} uses it to detect changes in source files. This is the most efficient and least resource-consuming option available on Linux for regular files.\ -The `system` value will use system poll methods (via ivykis) like `port-timer` `port` `dev_poll` `epoll-timerfd` `epoll` `kqueue` `ppoll` `poll` and `uring`. For more information about how to control the system polling methods used, see How content changes are followed in file() and wildcard-file() sources. +The `system` value will use system poll methods (via ivykis) like `port-timer` `port` `dev_poll` `epoll-timerfd` `epoll` `kqueue` `ppoll` `poll` and `uring`. **NOTE:** Using `inotify` also requires setting monitor-method() to `inotify`. {: .notice--info} diff --git a/_includes/doc/admin-guide/warnings/file-source-deprecation-warning.md b/_includes/doc/admin-guide/warnings/file-source-deprecation-warning.md new file mode 100644 index 00000000..a920cccb --- /dev/null +++ b/_includes/doc/admin-guide/warnings/file-source-deprecation-warning.md @@ -0,0 +1,3 @@ +![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:** +Currently, the file() source is maintained for compatibility, but for regular files — especially when using wildcards in the filename — it is recommended to use the wildcard-file() source, as it provides better long-term support and more configuration options. The only real use case for the legacy file() source is when you need to read kernel messages. +{: .notice--warning} diff --git a/_includes/doc/admin-guide/warnings/file-source-follow-warning.md b/_includes/doc/admin-guide/warnings/file-source-follow-warning.md index 9f00826f..f68fe553 100644 --- a/_includes/doc/admin-guide/warnings/file-source-follow-warning.md +++ b/_includes/doc/admin-guide/warnings/file-source-follow-warning.md @@ -1,2 +1,3 @@ -![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:** As the follow-freq(), follow-method(), monitor-method(), and the monitor-freq() options could have performance penalty effects, it is important to understand how the file and directory monitoring operates depending on these values. For details, refer to How content changes are followed in file() and wildcard-file() sources. +![]({{ site.baseurl}}/assets/images/caution.png) **CAUTION:** +As the follow-freq(), follow-method(), monitor-method(), and the monitor-freq() options could have performance penalty effects, it is important to understand how the file and directory monitoring operates depending on these values. For details, refer to How content changes are followed in file() and wildcard-file() sources. {: .notice--warning} diff --git a/doc/_admin-guide/060_Sources/020_File/000_File_source_options.md b/doc/_admin-guide/060_Sources/020_File/000_File_source_options.md new file mode 100644 index 00000000..36733d3b --- /dev/null +++ b/doc/_admin-guide/060_Sources/020_File/000_File_source_options.md @@ -0,0 +1,52 @@ +--- +title: file() source options +id: adm-src-file-opt +description: >- + This section describes the options of the file() source in {{ site.product.short_name }}. +--- + +{% include doc/admin-guide/warnings/file-source-deprecation-warning.md %} + +The file() driver has the following options: + +{% include doc/admin-guide/options/default-facility.md %} + +{% include doc/admin-guide/options/default-priority.md %} + +{% include doc/admin-guide/options/encoding.md %} + +{% include doc/admin-guide/options/source-flags.md %} + +{% include doc/admin-guide/options/follow-freq.md %} + +{% include doc/admin-guide/options/follow-method.md %} + +{% include doc/admin-guide/options/hook.md %} + +{% include doc/admin-guide/options/keep-timestamp.md %} + +{% include doc/admin-guide/options/log-fetch-limit.md %} + +{% include doc/admin-guide/options/log-iw-size.md %} + +{% include doc/admin-guide/options/log-msg-size.md %} + +{% include doc/admin-guide/options/log-prefix.md %} + +{% include doc/admin-guide/options/multi-line-garbage.md %} + +{% include doc/admin-guide/options/multi-line-mode.md %} + +{% include doc/admin-guide/options/multi-line-prefix.md %} + +{% include doc/admin-guide/options/multi-line-suffix.md %} + +{% include doc/admin-guide/options/multi-line-timeout.md %} + +{% include doc/admin-guide/options/pad-size.md %} + +{% include doc/admin-guide/options/program-override.md %} + +{% include doc/admin-guide/options/tags.md %} + +{% include doc/admin-guide/options/time-zone.md %} diff --git a/doc/_admin-guide/060_Sources/020_File/000_Notes_on_reading_kernel_messages.md b/doc/_admin-guide/060_Sources/020_File/001_Notes_on_reading_kernel_messages.md similarity index 100% rename from doc/_admin-guide/060_Sources/020_File/000_Notes_on_reading_kernel_messages.md rename to doc/_admin-guide/060_Sources/020_File/001_Notes_on_reading_kernel_messages.md diff --git a/doc/_admin-guide/060_Sources/020_File/README.md b/doc/_admin-guide/060_Sources/020_File/README.md index 8194be1c..67262029 100644 --- a/doc/_admin-guide/060_Sources/020_File/README.md +++ b/doc/_admin-guide/060_Sources/020_File/README.md @@ -4,9 +4,11 @@ short_title: file id: adm-src-file description: >- Collects log messages from plain-text files, for example, from the logfiles of - an Apache webserver. If you want to use wildcards in the filename, use the [[wildcard-file() source|adm-src-wild]]. Currently, {{ site.product.short_name }} supports the file() source to maintain certain compatibilities, but it is advised to use the wildcard-file() source for longevity reasons and more configuration options. + an Apache webserver. --- +{% include doc/admin-guide/warnings/file-source-deprecation-warning.md %} + The {{ site.product.short_name }} application notices if a file is renamed or replaced with a new file, so it can correctly follow the file even if logrotation is used. When {{ site.product.short_name }} is restarted, it records the position of the last @@ -14,7 +16,7 @@ sent log message in the /var/lib/syslog-ng/syslog-ng.persist file, and continues to send messages from this position after the restart. The file driver has a single required parameter specifying the file to -open. If you want to use wildcards in the filename, use the [[wildcard-file() source|adm-src-wild]]. +open. If you want to use wildcards in the filename, use the wildcard-file() source. For the list of available optional parameters, see file() source options. {% include doc/admin-guide/warnings/file-source-follow-warning.md %} @@ -49,5 +51,3 @@ treats messages received from files as sent by the kern facility. Use the **default-facility()** and **default-priority()** options in the source definition to assign a different facility if needed. {: .notice--info} - -For the configuration options available in the `file()` source, see wildcard-file() source options. \ No newline at end of file