From 097934678839b5a1ecdffef0eb4582b125860919 Mon Sep 17 00:00:00 2001
From: Kentaro Hayashi <hayashi@clear-code.com>
Date: Fri, 13 Mar 2026 18:42:20 +0900
Subject: [PATCH] buffer: warn if default timekey (1d) will be used (#5276)

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

**What this PR does / why we need it**:

By default, the value of timekey interval was set as interval 1d.
Without changing flush related parameters, it will not be flushed at all
in that period. This behavior is intentional design, but it might be
surprised in some use cases.

So, in some doubtful use-case, emit warning for it.

```
Before:

  no buffer configuration # no warning

  <buffer>
    @type file # no warning
  </buffer>

  <buffer time>
    @type file # no warning
  </buffer>

  <buffer []>
    @type file # no warning
  </buffer>

After:

  no buffer configuration # warning

  <buffer>
    @type file # warning
  </buffer>

  <buffer time>
    @type file # warning
  </buffer>

  <buffer []>
    @type file # no warning
  </buffer>

```

**Docs Changes**:

N/A

**Release Note**:

N/A

Signed-off-by: Kentaro Hayashi <hayashi@clear-code.com>
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
---
 lib/fluent/plugin/out_file.rb | 10 ++++++++
 test/command/test_fluentd.rb  | 48 +++++++++++++++++++++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/lib/fluent/plugin/out_file.rb b/lib/fluent/plugin/out_file.rb
index a5bed3ea61..13f6c695cf 100644
--- a/lib/fluent/plugin/out_file.rb
+++ b/lib/fluent/plugin/out_file.rb
@@ -117,7 +117,17 @@ def configure(conf)
       configured_time_slice_format = conf['time_slice_format']
 
       if conf.elements(name: 'buffer').empty?
+        # no <buffer> section, default time chunk key and timekey (1d) will be used.
+        log.warn "default timekey interval (1d) will be used because of missing <buffer> section. To change the output frequency, please modify the timekey value"
+
         conf.add_element('buffer', 'time')
+      else
+        unless conf.elements(name: 'buffer').first.has_key?('timekey')
+          if conf.elements(name: 'buffer').first.arg != "[]"
+            # with <buffer> section (except <buffer []>), and no timekey
+            log.warn "default timekey interval (1d) will be used. To change the output frequency, please modify the timekey value"
+          end
+        end
       end
       buffer_conf = conf.elements(name: 'buffer').first
       # Fluent::PluginId#configure is not called yet, so we can't use #plugin_root_dir here.
diff --git a/test/command/test_fluentd.rb b/test/command/test_fluentd.rb
index b7b8095355..4eb295f0b7 100644
--- a/test/command/test_fluentd.rb
+++ b/test/command/test_fluentd.rb
@@ -1712,4 +1712,52 @@ def create_config_include_dir_configuration(config_path, config_dir, yaml_format
                          expected_warning_message)
     end
   end
+
+  sub_test_case "test suspicious timekey interval (1d) in out_file configuration" do
+    data('without buffer' => {buffer: nil, buffer_arg: nil, message: :missing_buffer},
+         'buffer' => {buffer: true, buffer_arg: '', message: :warning},
+         'buffer time' => {buffer: true, buffer_arg: 'time', message: :warning},
+         'buffer []' => {buffer: true, buffer_arg: '[]', message: nil})
+    test 'warn the default value of timekey (1d) is used as-is' do |data|
+      prefix = "default timekey interval (1d) will be used"
+      advice = "To change the output frequency, please modify the timekey value"
+      missing_warning = "#{prefix} because of missing <buffer> section. #{advice}"
+      warning = "#{prefix}. #{advice}"
+
+      conf_path = if data[:buffer]
+                    create_conf_file("warning.conf", <<~EOF)
+                      <system>
+                        config_include_dir ""
+                      </system>
+                      <match>
+                        @type file
+                        tag test
+                        path #{@tmp_dir}/test.log
+                        <buffer #{data[:buffer_arg]}>
+                          @type file
+                        </buffer>
+                      </match>
+                    EOF
+                  else
+                    create_conf_file("warning.conf", <<~EOF)
+                      <system>
+                        config_include_dir ""
+                      </system>
+                      <match>
+                        @type file
+                        tag test
+                        path #{@tmp_dir}/test.log
+                      </match>
+                    EOF
+      end
+      case data[:message]
+      when :missing_buffer
+        assert_log_matches(create_cmdline(conf_path, '--dry-run'), missing_warning, patterns_not_match: [warning])
+      when :warning
+        assert_log_matches(create_cmdline(conf_path, '--dry-run'), "warning", patterns_not_match: [missing_warning])
+      else
+        assert_log_matches(create_cmdline(conf_path, '--dry-run'), patterns_not_match: [warning, missing_warning])
+      end
+    end
+  end
 end