> For the complete documentation index, see [llms.txt](https://docs.fluentbit.io/manual/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fluentbit.io/manual/5.0/data-pipeline/outputs/file.md). # File {% hint style="info" %} **Supported event types:** `logs` `metrics` {% endhint %} 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](#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](/manual/5.0/administration/configuring-fluent-bit/classic-mode/record-accessor.md) expressions. | *none* | | `format` | The [format](#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](/manual/5.0/administration/configuring-fluent-bit/classic-mode/record-accessor.md) expressions, which must follow a static prefix. | *none* | | `rotate` | Enable size-based [log rotation](#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](/manual/5.0/administration/multithreading.md#outputs) 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. ```json {"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: {% tabs %} {% tab title="fluent-bit.yaml" %} ```yaml pipeline: inputs: - name: mem outputs: - name: file match: '*' format: template template: '{time} used={Mem.used} free={Mem.free} total={Mem.total}' ``` {% endtab %} {% tab title="fluent-bit.conf" %} ``` [INPUT] Name mem [OUTPUT] Name file Match * Format template Template {time} used={Mem.used} free={Mem.free} total={Mem.total} ``` {% endtab %} {% endtabs %} 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 `.`. 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](#format): default (`out_file`), `plain`, `csv`, `ltsv`, `template`, and `msgpack`. File operations are thread-safe, so rotation can be used alongside multiple [workers](/manual/5.0/administration/multithreading.md#outputs). ### 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: {% tabs %} {% tab title="fluent-bit.yaml" %} ```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 ``` {% endtab %} {% tab title="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 ``` {% endtab %} {% endtabs %} ## Dynamic destinations Dynamic destinations are available in Fluent Bit version 5.1 and greater. The `path` and `file` parameters accept [record accessor](/manual/5.0/administration/configuring-fluent-bit/classic-mode/record-accessor.md) 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`: {% tabs %} {% tab title="fluent-bit.yaml" %} ```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 ``` {% endtab %} {% tab title="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 ``` {% endtab %} {% endtabs %} ## 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: ```shell fluent-bit -i cpu -o file -p path=output.txt ``` ### Configuration file In your main configuration file append the following: {% tabs %} {% tab title="fluent-bit.yaml" %} ```yaml pipeline: inputs: - name: cpu tag: cpu outputs: - name: file match: '*' path: output_dir ``` {% endtab %} {% tab title="fluent-bit.conf" %} ``` [INPUT] Name cpu Tag cpu [OUTPUT] Name file Match * Path output_dir ``` {% endtab %} {% endtabs %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.fluentbit.io/manual/5.0/data-pipeline/outputs/file.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.