# Tail {% hint style="info" %} **Supported event types:** `logs` {% endhint %} The *Tail* input plugin lets you monitor text files. Its behavior is similar to the `tail -f` shell command. The plugin reads every matched file in the `Path` pattern. For every new line found (separated by a newline character `\n`), it generates a new record. Optionally, you can use a database file so the plugin can have a history of tracked files and a state of offsets. This helps resume a state if the service is restarted. ## Configuration parameters The plugin supports the following configuration parameters: | Key | Description | Default | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `buffer_chunk_size` | Set the initial buffer size to read file data. This value is used to increase buffer size. The value must be according to the [Unit Size](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit#unit-sizes) specification. | `32k` | | `buffer_max_size` | Set the limit of the buffer size per monitored file. When a buffer needs to be increased, this value is used to restrict the memory buffer growth. If reading a file exceeds this limit, the file is removed from the monitored file list. The value must be according to the [Unit Size](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit#unit-sizes) specification. | `32k` | | `db` | Specify the database file to keep track of monitored files and offsets. Recommended to be unique per plugin. | *none* | | `db.compare_filename` | This option determines whether to review both `inode` and `filename` when retrieving stored file information from the database. `true` verifies both `inode` and `filename`, while `false` checks only the `inode`. To review the `inode` and `filename` in the database, refer [see `keep_state`](#tailing-files-keeping-state). | `false` | | `db.journal_mode` | Sets the journal mode for databases (`wal`). Enabling `wal` provides higher performance. `wal` isn't compatible with shared network file systems. | `wal` | | `db.locking` | Specify that the database will be accessed only by Fluent Bit. Enabling this feature helps increase performance when accessing the database but restricts external tools from querying the content. | `false` | | `db.sync` | Set a default synchronization (I/O) method. This flag affects how the internal SQLite engine does synchronization to disk. For more details about each option, see [the SQLite documentation](https://www.sqlite.org/pragma.html#pragma_synchronous). Most scenarios will be fine with `normal` mode. If you need full synchronization after every write operation, set `full` mode. `full` has a high I/O performance cost. Values: `extra`, `full`, `normal`, `off`. | `normal` | | `docker_mode` | If enabled, the plugin will recombine split Docker log lines before passing them to any parser. This mode can't be used at the same time as Multiline. | `false` | | `docker_mode_flush` | Wait period time in seconds to flush queued unfinished split lines. | `4` | | `docker_mode_parser` | Specify an optional parser for the first line of the Docker multiline mode. The parser name must be registered in the `parsers.conf` file. | *none* | | `event_batch_size` | Set the maximum number of bytes to process per iteration for files monitored in event mode (files promoted from static to event-based monitoring). This prevents a single input plugin from consuming too many resources when large amounts of data is available. | `50M` | | `exclude_path` | Set one or multiple shell patterns separated by commas to exclude files matching certain criteria. For example, `exclude_path *.gz,*.zip`. | *none* | | `exit_on_eof` | When reading a file, exit as soon as it reaches the end of the file. Used for bulk load and tests. | `false` | | `file_cache_advise` | Set the `posix_fadvise` in `POSIX_FADV_DONTNEED` mode. This reduces the usage of the kernel file cache. This option is ignored if not running on Linux. | `true` | | `generic.encoding` | Set the non-Unicode encoding of the file data. Supported values: `ShiftJIS`, `UHC`, `GBK`, `GB18030`, `Big5`, `Win866`, `Win874`, `Win1250`, `Win1251`, `Win1252`, `Win1253`, `Win1254`, `Win1255`, and `Win1256`. | *none* | | `ignore_active_older_files` | Ignore files that are older than the value set in `ignore_older` even if the file is being ingested. | `false` | | `ignore_older` | Ignores files older than `ignore_older`. Supports `m`, `h`, `d` (minutes, hours, days) syntax. | Read all. | | `inotify_watcher` | Set to `false` to use file stat watcher instead of `inotify`. | `true` | | `key` | When a message is unstructured (no parser applied), it's appended as a string under the key name `log`. This option lets you define an alternative name for that key. | `log` | | `mem_buf_limit` | Set a memory limit that the Tail plugin can use when appending data to the engine. If the limit is reached, it will be paused. When the data is flushed, it resumes. | *none* | | `offset_key` | If enabled, Fluent Bit appends the offset of the current monitored file as part of the record. The value assigned becomes the key in the map. | *none* | | `parser` | Specify the name of a parser to interpret the entry as a structured message. | *none* | | `path` | Pattern specifying a specific log file or multiple ones through the use of common wildcards. Allows multiple patterns separated by commas. | *none* | | `path_key` | If enabled, it appends the name of the monitored file as part of the record. The value assigned becomes the key in the map. | *none* | | `progress_check_interval` | Set the interval for checking file progress. This is an advanced option for fine-tuning file monitoring behavior. | `2s` | | `progress_check_interval_nsec` | Set the nanosecond component of the progress check interval. This is an advanced option used in conjunction with `progress_check_interval` for sub-second precision. | `0` | | `read_from_head` | For new discovered files on start (without a database offset/position), read the content from the head of the file, not tail. | `false` | | `read_newly_discovered_files_from_head` | For newly discovered files after startup (without a database offset/position), read the content from the head of the file, not tail. This differs from `read_from_head` which only applies to files discovered at startup. | `true` | | `refresh_interval` | The interval of refreshing the list of watched files in seconds. | `60` | | `rotate_wait` | Specify the number of extra time in seconds to monitor a file once it's rotated in case some pending data is flushed. | `5` | | `skip_empty_lines` | Skips empty lines in the log file from any further processing or output. | `false` | | `skip_long_lines` | When a monitored file reaches its buffer capacity due to a very long line (`buffer_max_size`), the default behavior is to stop monitoring that file. `skip_long_lines` alters that behavior and instructs Fluent Bit to skip long lines and continue processing other lines that fit into the buffer size. | `false` | | `static_batch_size` | Set the maximum number of bytes to process per iteration for the monitored static files (files that already exist upon Fluent Bit start). | `50M` | | `tag` | Set a tag with `regexextract` fields that will be placed on lines read. For example, `kube....`. Tag expansion is supported: if the tag includes an asterisk (`*`), that asterisk will be replaced with the absolute path of the monitored file, with slashes replaced by dots. See [Workflow of Tail + Kubernetes Filter](https://docs.fluentbit.io/manual/filters/kubernetes#workflow-of-tail--kubernetes-filter). | *none* | | `tag_regex` | Set a regular expression to extract fields from the filename. For example: `(?[a-z0-9](?:[-a-z0-9]*[a-z0-9])?(?:\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*)_(?[^_]+)_(?.+)-(?[a-z0-9]{64})\.log$`. | *none* | | `thread.ring_buffer.capacity` | Number of slots in the ring buffer for data entries when running in [threaded](https://docs.fluentbit.io/manual/administration/multithreading) mode. Each slot can hold one data entry. | `1024` | | `thread.ring_buffer.window` | Percentage threshold (1-100) of the ring buffer capacity at which a flush is triggered when running in [threaded](https://docs.fluentbit.io/manual/administration/multithreading) mode. | `5` | | `threaded` | Indicates whether to run this input in its own [thread](https://docs.fluentbit.io/manual/administration/multithreading#inputs). | `false` | | `truncate_long_lines` | When enabled, truncates lines that exceed the buffer capacity after input encoding conversion to UTF-8. Use this option when dealing with character encoding conversions that might expand the line length. | `false` | | `unicode.encoding` | Set the Unicode character encoding of the file data. This parameter requests two-byte aligned chunk and buffer sizes. If data isn't aligned for two bytes, Fluent Bit will use two-byte alignment automatically to avoid character breakages on consuming boundaries. Supported values: `UTF-16LE`, `UTF-16BE`, and `auto`. | *none* | | `watcher_interval` | Set the interval for the watcher that monitors symbolic link rotation. This is an advanced option for fine-tuning how often Fluent Bit checks if symbolic links have been rotated. | `2s` | ## Buffers and memory management The Tail plugin uses buffers to efficiently read and process log files. Understanding how these buffers work helps optimize memory usage and performance. ### File buffers versus Fluent Bit chunks When a file is opened for monitoring, the Tail plugin allocates a buffer in memory of `buffer_chunk_size` bytes (defaults to 32 KB). This buffer is used to read data from the file. If a single record (line) is longer than `buffer_chunk_size`, the buffer will grow up to `buffer_max_size` to accommodate it. {% hint style="info" %} These buffers are per-file. If you're monitoring many files, each file gets its own buffer, which can significantly increase memory usage. {% endhint %} ### From buffers to chunks Inside each file buffer, multiple lines or records might exist. The plugin processes these records and converts them to MessagePack format (binary serialization). This MessagePack data is then appended to what Fluent Bit calls a *chunk*, which is a collection of serialized records that belong to the same tag. Although Fluent Bit has a soft limit of 2 MB for chunks, input plugins like Tail can generate MessagePack buffers larger than 2 MB, and the final chunk can exceed this soft limit. ### Memory protection with `mem_buf_limit` If Fluent Bit isn't configured to use filesystem buffering, it needs mechanisms to protect against high memory consumption during backpressure scenarios (for example, when destination endpoints are down or network issues occur). The `mem_buf_limit` option restricts how much memory in chunks an input plugin can use. When filesystem buffering is enabled, memory management works differently. For more details, see [Buffering](https://docs.fluentbit.io/manual/data-pipeline/buffering) and [Backpressure](https://docs.fluentbit.io/manual/administration/backpressure). ## Database file File positioning behavior varies based on the presence or absence of a database file. If a database file is present, the plugin restores the last known position (offset) from the database. If no previous position exists and `read_from_head` is `false`, it starts monitoring from the end of the file. If no database file is present, positioning behavior depends on the value of `read_from_head`: * When `read_from_head` is `true`, the plugin reads from the beginning of the file. * When `read_from_head` is `false`, the plugin starts monitoring from the end of the file (classic "tail" behavior). This means that only new content written after Fluent Bit starts will be monitored. The database file essentially stores `inode=offset` so it should be unique per instance of the plugin, for example if you have two tail inputs then use two separate `db` files for each. That way each tail input can independently track its own state. {% hint style="info" %} **Data Reliability and Recovery** During normal operations and graceful shutdowns (SIGTERM), Fluent Bit synchronizes file offsets with the database to ensure no data is lost. In unexpected shutdowns (for example, system crash, power loss, SIGKILL), Fluent Bit guarantees *at-least-once* delivery. The database offset might slightly trail the actual processed position if an unexpected shutdown occurs after data is processed but before the new offset is committed to the database. Upon restart, Fluent Bit resumes from the last committed checkpoint. This ensures no data is lost, though it might result in the re-ingestion of a minimal amount of previously processed records (duplication). {% endhint %} {% hint style="info" %} The `unicode.encoding` parameter is dependent on the `simdutf` library, which is itself dependent on C++ version 11 or later. In environments that use earlier versions of C++, the `unicode.encoding` parameter will fail. Additionally, the `auto` setting for `unicode.encoding` isn't supported in all cases, and can make mistakes when it tries to guess the correct encoding. For best results, use either the `UTF-16LE` or `UTF-16BE` setting if you know the encoding type of the target file. {% endhint %} ## Monitor a large number of files To monitor a large number of files, you can increase the `inotify` settings in your Linux environment by modifying the following `sysctl` parameters: ``` sysctl fs.inotify.max_user_watches=LIMIT1 sysctl fs.inotify.max_user_instances=LIMIT2 ``` Replace *`LIMIT1`* and *`LIMIT2`* with the integer values of your choosing. Higher values raise your `inotify` limit accordingly. These changes revert upon reboot unless you write them to the appropriate `inotify.conf` file. Writing to the file ensures the settings persist across reboots. The specific filename can vary depending on how you built and installed Fluent Bit. For example, to write changes to a file named `fluent-bit_fs_inotify.conf`, run the following commands: ```shell mkdir -p /etc/sysctl.d echo fs.inotify.max_user_watches = LIMIT1 >> /etc/sysctl.d/fluent-bit_fs_inotify.conf echo fs.inotify.max_user_instances = LIMIT2 >> /etc/sysctl.d/fluent-bit_fs_inotify.conf ``` Replace *`LIMIT1`* and *`LIMIT2`* with the integer values of your choosing. You can also provide a custom systemd configuration file that overrides the default systemd settings for Fluent Bit. This override file must be located at `/etc/systemd/system/fluent-bit.service.d/override.conf` or `/etc/systemd/system/fluent-bit.service.d/override.yaml` depending on the configuration you choose. For example, you can add one of these snippets to your override file to raise the number of files that the Tail plugin can monitor: {% tabs %} {% tab title="override.yaml" %} ```yaml service: limitnofile: LIMIT ``` {% endtab %} {% tab title="override.conf" %} ``` [Service] LimitNOFILE=LIMIT ``` {% endtab %} {% endtabs %} Replace *`LIMIT`* with the integer value of your choosing. If you don't already have an override file, you can use the following command to create one in the correct directory: ```shell systemctl edit fluent-bit.service ``` ## Multiline support Fluent Bit 1.8 and later supports multiline core capabilities for the Tail input plugin. Fluent Bit supports the both the old and new configuration mechanisms. To avoid breaking changes, users are encouraged to use the latest one. The two mechanisms are: * Multiline core * Old multiline ### Multiline core Multiline core is exposed by the following configuration: | Key | Description | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `multiline.parser` | Specify one or multiple [Multiline Parser definitions](https://docs.fluentbit.io/manual/data-pipeline/parsers/multiline-parsing) to apply to the content. | [Multiline Parser](https://docs.fluentbit.io/manual/data-pipeline/parsers/multiline-parsing) provides built-in configuration modes. When using a new `multiline.parser` definition, you must disable the old configuration from your tail section like: * `parser` * `parser_firstline` * `parser_N` * `multiline` * `multiline_flush` * `docker_mode` ### Multiline and containers If you are running Fluent Bit to process logs coming from containers like Docker or CRI, you can use the built-in modes. This helps reassemble large messages originally split by Docker or CRI: {% tabs %} {% tab title="fluent-bit.yaml" %} ```yaml pipeline: inputs: - name: tail path: /var/log/containers/*.log multiline.parser: docker, cri ``` {% endtab %} {% tab title="fluent-bit.conf" %} ``` [INPUT] name tail path /var/log/containers/*.log multiline.parser docker, cri ``` {% endtab %} {% endtabs %} The two options separated by a comma mean Fluent Bit will try each parser in the list in order, applying the first one that matches the log. It will use the first parser which has a `start_state` that matches the log. For example, it will first try `docker`, and if `docker` doesn't match, it will then try `cri`. ### Old multiline configuration parameters For the old multiline configuration, the following options exist to configure the handling of multiline logs: | Key | Description | Default | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | | `multiline` | If enabled, the plugin will try to discover multiline messages and use the proper parsers to compose the outgoing messages. When this option is enabled the Parser option isn't used. | `off` | | `multiline_flush` | Wait period time in seconds to process queued multiline messages. | `4` | | `parser_firstline` | Name of the parser that matches the beginning of a multiline message. The regular expression defined in the parser must include a group name (named `capture`), and the value of the last match group must be a string. | *none* | | `parser_N` | Optional. Extra parser to interpret and structure multiline entries. This option can be used to define multiple parsers. For example, `parser_1 ab1`, `parser_2 ab2`, `parser_N abN`. | *none* | ### Old Docker mode configuration parameters Docker mode exists to recombine JSON log lines split by the Docker daemon due to its line length limit. To use this feature, configure the tail plugin with the corresponding parser and then enable Docker mode using the `docker_mode`, `docker_mode_flush`, and `docker_mode_parser` parameters documented in the main [configuration parameters](#configuration-parameters) table. ## Get started To tail text or log files, 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 parse text files with the following options: ```shell fluent-bit -i tail -p path=/var/log/syslog -o stdout ``` ### Configuration file Append the following in your main configuration file: {% tabs %} {% tab title="fluent-bit.yaml" %} ```yaml pipeline: inputs: - name: tail path: /var/log/syslog outputs: - stdout: match: * ``` {% endtab %} {% tab title="fluent-bit.conf" %} ``` [INPUT] Name tail Path /var/log/syslog [OUTPUT] Name stdout Match * ``` {% endtab %} {% endtabs %} ### Old multiline example When using multiline configuration you need to first specify `Multiline On` in the configuration and use the `Parser_Firstline` and additional parser parameters `Parser_N` if needed. For example, you might be trying to read the following Java stack trace as a single event: ``` Dec 14 06:41:08 Exception in thread "main" java.lang.RuntimeException: Something has gone wrong, aborting! at com.myproject.module.MyProject.badMethod(MyProject.java:22) at com.myproject.module.MyProject.oneMoreMethod(MyProject.java:18) at com.myproject.module.MyProject.anotherMethod(MyProject.java:14) at com.myproject.module.MyProject.someMethod(MyProject.java:10) at com.myproject.module.MyProject.main(MyProject.java:6) ``` Specify a `parser_firstline` parameter that matches the first line of a multiline event. When a match is made, Fluent Bit reads all future lines until another match with `parser_firstline` is made. In this case you can use the following parser, which extracts the time as `time` and the remaining portion of the multiline as `log`. {% tabs %} {% tab title="parsers.yaml" %} ```yaml parsers: - name: multiline format: regex regex: '/(?