File

Supported event types: logs metrics

The File output plugin lets you write the data received through the input plugin to file.

Configuration parameters

Key	Description	Default
fallback_file	Static filename used when a fallback action is applied. Required whenever path or file uses a record accessor. See Dynamic destinations.	none
fallback_path	Static directory path used together with fallback_file when a fallback action is applied.	none
file	Set filename to store the records. If not set, the filename will be the tag associated with the records. Supports record accessor expressions.	none
format	The format of the file content.	none
max_dynamic_files	Maximum number of distinct destinations that record accessor expressions can resolve to. Set to 0 for unlimited.	1024
mkdir	Recursively create output directory if it doesn't exist. Permissions set to 0755.	false
on_limit_reached	Action to take for a record whose destination would exceed max_dynamic_files. Accepted values: error, drop, fallback.	error
on_missing_field	Action to take for a record whose record accessor field is missing, or resolves to an unsafe value. Accepted values: error, drop, fallback.	error
path	Directory path to store files. If not set, Fluent Bit will write the files in its own working directory. Supports record accessor expressions, which must follow a static prefix.	none
rotate	Enable size-based log rotation. When enabled, files that exceed rotate_max_size are rotated and optionally compressed.	false
rotate_gzip	Compress rotated files using gzip. Only applies when rotate is enabled.	true
rotate_max_files	Maximum number of rotated files to retain per output file. Oldest files are deleted first. Must be 1 or greater. Only applies when rotate is enabled.	7
rotate_max_size	Maximum size of the active output file before rotation is triggered. Supports size suffixes: k (kilobytes), m (megabytes), g (gigabytes). Only applies when rotate is enabled.	100M
workers	The number of workers to perform flush operations for this output.	1

Format

This plugin uses the following formats:

out_file

Output time, tag, and json records. There are no configuration parameters for out_file.

tag: [time, {"key1":"value1", "key2":"value2", "key3":"value3"}]

Plain

Output the records as JSON (without additional tag and timestamp attributes). There are no configuration parameters for plain format.

{"key1":"value1", "key2":"value2", "key3":"value3"}

CSV

Output the records in CSV format. CSV mode supports additional configuration parameters.

Key	Description	Default
csv_column_names	Add column names (keys) as the first line of the output file.	false
delimiter	The character to separate each field. Accepted values: \t (or tab), (space), or , (comma). Other values are ignored and fall back to the default.	,

time[delimiter]"value1"[delimiter]"value2"[delimiter]"value3"

LTSV

Output the records in LTSV format. LTSV mode supports additional configuration parameters.

Key	Description	Default
delimiter	The character to separate each pair.	\t
label_delimiter	The character to separate label and the value.	:

field1[label_delimiter]value1[delimiter]field2[label_delimiter]value2\n

Template

Output the records using a custom format template.

Key	Description	Default
template	The format string.	{time} {message}

This accepts a formatting template and fills placeholders using corresponding values in a record.

For example, if you set up the configuration like the following:

fluent-bit.yaml

pipeline:
  inputs:
    - name: mem

  outputs:
    - name: file
      match: '*'
      format: template
      template: '{time} used={Mem.used} free={Mem.free} total={Mem.total}'

fluent-bit.conf

[INPUT]
  Name mem

[OUTPUT]
  Name file
  Match *
  Format template
  Template {time} used={Mem.used} free={Mem.free} total={Mem.total}

You will get the following output:

1564462620.000254 used=1045448 free=31760160 total=32805608

Log rotation

The File output plugin supports size-based log rotation.

When rotate is enabled, the plugin monitors the size of each output file. Once a file exceeds rotate_max_size, the next flush rotates the file by renaming it with a timestamp suffix in the format <filename>.<YYYYMMDD_HHMMSS_XXXXXXXX>. The YYYYMMDD_HHMMSS is the machine-local timestamp of the rotation, and XXXXXXXX is a random hex identifier that guarantees unique filenames if multiple rotations happen within the same second.

If rotate_gzip is enabled (the default), rotated files are compressed with gzip and stored with an additional .gz extension (for example, cpu.log.20260512_134500_a1b2c3d4.gz).

The plugin retains up to rotate_max_files rotated files per output file. When the limit is reached, the oldest rotated files are deleted automatically.

Log rotation works with all supported output formats: default (out_file), plain, csv, ltsv, template, and msgpack. File operations are thread-safe, so rotation can be used alongside multiple workers.

Log rotation example

The following configuration writes CPU metrics to file with rotation enabled. Files are rotated at 50 MB and the five most recent rotated files are retained with gzip compression:

fluent-bit.yaml

pipeline:
  inputs:
    - name: cpu
      tag: cpu

  outputs:
    - name: file
      match: '*'
      path: /var/log/fluent-bit
      file: cpu.log
      rotate: true
      rotate_max_size: 50M
      rotate_max_files: 5
      rotate_gzip: true

fluent-bit.conf

[INPUT]
  Name cpu
  Tag  cpu

[OUTPUT]
  Name             file
  Match            *
  Path             /var/log/fluent-bit
  File             cpu.log
  Rotate           true
  Rotate_Max_Size  50M
  Rotate_Max_Files 5
  Rotate_Gzip      true

Dynamic destinations

Dynamic destinations are available in Fluent Bit version 5.1 and greater.

The path and file parameters accept record accessor expressions, which lets one output instance write records to different files based on the content of each record. Fluent Bit treats a destination as dynamic when path or file contains a $ character.

Two rules apply when you configure a dynamic destination:

• A dynamic path must begin with a static prefix. Fluent Bit rejects a path that starts with a record accessor, so that generated paths always stay under a directory you chose.

• You must set fallback_file. Fluent Bit fails to start if a record accessor is used without it, because there would be nowhere to write records whose destination can't be resolved.

Fluent Bit rejects a resolved destination as unsafe when the filename is empty, is . or .., or contains a path separator or one of the characters :, *, ?, ", <, >, or |. Path components of . and .. are also rejected. This keeps a record value from redirecting output outside of the configured directory.

Generated directories are only created if you also enable mkdir.

Actions for unresolved destinations

Two settings control what happens to a record whose destination Fluent Bit can't use. on_missing_field applies when the record accessor field is missing or resolves to an unsafe value, and on_limit_reached applies when writing to a new destination would exceed max_dynamic_files. Both accept the same actions:

Action	Behavior
error	Log an error and fail the flush, so the chunk is retried.
drop	Log a warning and discard the record.
fallback	Write the record to fallback_path and fallback_file instead.

The max_dynamic_files limit counts distinct destinations that this output instance has written to, which bounds the number of files a high-cardinality record field can create. Records that resolve to a destination already in use aren't affected by the limit.

Dynamic destination example

The following configuration writes each record to a file named after its app field, under a per-namespace directory. Records without both fields go to /var/log/fluent-bit/unrouted.log:

fluent-bit.yaml

pipeline:
  outputs:
    - name: file
      match: '*'
      path: /var/log/fluent-bit/$namespace
      file: $app.log
      mkdir: true
      max_dynamic_files: 256
      on_missing_field: fallback
      on_limit_reached: fallback
      fallback_path: /var/log/fluent-bit
      fallback_file: unrouted.log

fluent-bit.conf

[OUTPUT]
  Name              file
  Match             *
  Path              /var/log/fluent-bit/$namespace
  File              $app.log
  Mkdir             true
  Max_Dynamic_Files 256
  On_Missing_Field  fallback
  On_Limit_Reached  fallback
  Fallback_Path     /var/log/fluent-bit
  Fallback_File     unrouted.log

Get started

You can run the plugin from the command line or through the configuration file.

Command line

From the command line you can let Fluent Bit count up a data with the following options:

fluent-bit -i cpu -o file -p path=output.txt

Configuration file

In your main configuration file append the following:

fluent-bit.yaml

pipeline:
  inputs:
    - name: cpu
      tag: cpu

  outputs:
    - name: file
      match: '*'
      path: output_dir

fluent-bit.conf

[INPUT]
  Name cpu
  Tag  cpu

[OUTPUT]
  Name  file
  Match *
  Path  output_dir