# System Configuration

This article describes Fluentd's system configurations for the `<system>` section and command-line options.

## Overview

System Configuration is one way to set up system-wide configuration such as enabling RPC, multiple workers, etc.

## Parameters

### `workers`

| type    | default | version |
| ------- | ------- | ------- |
| integer | 1       | 0.14.12 |

Specifies the number of workers.

### `restart_worker_interval`

| type | default | version |
| ---- | ------- | ------- |
| time | 0       | 1.15.0  |

Specifies interval to restart workers that has stopped for some reason. By default, Fluentd immediately restarts stopped workers. You can use this option for stopping workers for a certain period of time.

### `root_dir`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 0.14.11 |

Specifies the root directory.

### `log_level`

| type | default | version |
| ---- | ------- | ------- |
| enum | "info"  | 0.14.0  |

Specifies the log level e.g. `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.

### `suppress_repeated_stacktrace`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.0  |

Suppresses the repeated stacktrace.

### `emit_error_log_interval`

| type | default | version |
| ---- | ------- | ------- |
| time | nil     | 0.14.0  |

Specifies the time value of the emitting of error log interval.

### `ignore_repeated_log_interval`

| type | default | version |
| ---- | ------- | ------- |
| time | nil     | 1.10.2  |

Specify interval to ignore repeated log/stacktrace messages.

See also [Logging article](https://docs.fluentd.org/logging#ignore_repeated_log_interval).

### `ignore_same_log_interval`

| type | default | version |
| ---- | ------- | ------- |
| time | nil     | 1.11.3  |

Specify interval to ignore same log/stacktrace messages.

See also [Logging article](https://docs.fluentd.org/logging#ignore_same_log_interval).

### `suppress_config_dump`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.0  |

Suppresses the configuration dump.

### `log_event_verbose`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.12 |

Logs event verbosely.

### `without_source`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.0  |

Invokes fluentd without input plugins.

### `with_source_only`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 1.18.0  |

Not supported on Windows.

Invokes a fluentd only with input plugins.

See [Source Only Mode](https://docs.fluentd.org/deployment/source-only-mode) for details.

See also [source\_only\_buffer section](#less-than-source_only_buffer-greater-than-section).

### `rpc_endpoint`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 0.14.0  |

Specifies an RPC endpoint. Refer to the [RPC](https://docs.fluentd.org/deployment/rpc) article for more detail.

### `enable_get_dump`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 0.14.0  |

Enables to get dump.

### `process_name`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 0.14.0  |

Specifies the process name.

### `enable_msgpack_time_support`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.9.0   |

Allows `Time` object in buffer's MessagePack serde. This is useful when the log contains multiple time fields.

### `file_permission`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 0.14.0  |

Specifies the file permission in the octal format.

### `dir_permission`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 0.14.0  |

Specifies the directory permission in the octal format.

### `strict_config_value`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 1.8.0   |

Parses config values strictly. Invalid numerical or boolean values are not allowed. Fluentd raises configuration error instead of replacing them with `0` or `true` implicitly.

### `disable_shared_socket`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 1.12.1  |

Force disable the shared socket which is for listening a same port across multiple worker processes. When the shared socket is enabled (it's the default behavior), a socket is always created to enable workers to communicate with the supervisor. On Windows, it consumes a dynamic (a.k.a ephemeral) TCP port. If you don't prefer it, set this option as `true`. When it's disabled, you may not use plugins that listen a port such as in\_forward, in\_http and in\_syslog.

### `config_include_dir`

| type   | default              | version |
| ------ | -------------------- | ------- |
| string | "/etc/fluent/conf.d" | 1.19.0  |

Specifies the additional include directory which is enabled by default. If there is any configuration file under `config_include_dir` directory, it will be loaded without specifying `@include` directive.

If you want to disable this auto-load feature, set `config_include_dir ""` explicitly.

### `enable_jit` (experimental)

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 1.15.2  |

Enable JIT for worker processes. Internally, this configuration enables Ruby's `--jit` command-line option.

### `enable_input_metrics`

| type | default | version |
| ---- | ------- | ------- |
| bool | true    | 1.14.0  |

Specifies whether measuring input metrics should be enabled or not. Since v1.19.0, the default value is changed to `true`.

### `enable_size_metrics`

| type | default | version |
| ---- | ------- | ------- |
| bool | nil     | 1.14.0  |

Specifies whether measuring record size metrics should be enabled or not. It can be useful for calculating flow rate on Fluentd instances.

### `<log>` section

#### `path`

| type   | default | version |
| ------ | ------- | ------- |
| string | nil     | 1.18.0  |

Specifies the log file path.

Please see also [Output to Log File](https://docs.fluentd.org/logging#output-to-log-file).

#### `format`

| type | default | version |
| ---- | ------- | ------- |
| enum | text    | 0.14.20 |

Specifies the logging format e.g. `text` or `json`.

#### `time_format`

| type   | default                | version |
| ------ | ---------------------- | ------- |
| string | `%Y-%m-%d %H:%M:%S %z` | 0.14.20 |

Specifies time format.

#### `rotate_age`

| type            | default | version |
| --------------- | ------- | ------- |
| enum or integer | 7       | 1.13.0  |

Specifies `daily`, `weekly`, `monthly` or integer which indicates age of log rotation.

By default, Fluentd does not rotate log files. You need to specify `rotate_age` or `rotate_size` options explicitly to enable log rotation.

NOTE: When enabling log rotation on Windows, log files are separated into `log-supervisor-0.log`, `log-0.log`, ..., `log-N.log` where `N` is `generation - 1` due to the system limitation. Windows does not permit delete and rename files simultaneously owned by another process.

Please see also [Log Rotation Setting](https://docs.fluentd.org/logging#log-rotation-setting).

#### `rotate_size`

| type | default | version |
| ---- | ------- | ------- |
| size | 1048576 | 1.13.0  |

Specifies log file size limitation.

By default, Fluentd does not rotate log files. You need to specify `rotate_age` or `rotate_size` options explicitly to enable log rotation.

NOTE: When enabling log rotation on Windows, log files are separated into `log-supervisor-0.log`, `log-0.log`, ..., `log-N.log` where `N` is `generation - 1` due to the system limitation. Windows does not permit delete and rename files simultaneously owned by another process.

Please see also [Log Rotation Setting](https://docs.fluentd.org/logging#log-rotation-setting).

#### `forced_stacktrace_level`

| type | default | version |
| ---- | ------- | ------- |
| enum | "none"  | 1.19.0  |

Specifies `none` or the log level e.g. `trace`, `debug`, `info`, `warn`, `error`, or `fatal`.

If you set a log level for `forced_stacktrace_level`, log levels of stacktraces are forced to that level.

Example:

```
<system>
  log_level info # This is the default. You can omit this.
  <log>
    forced_stacktrace_level info
  </log>
</system>
```

This setting results in the following behavior:

* All stacktraces initially with `info` level (`log_level`) or higher will be forcibly logged with `info` level (`forced_stacktrace_level`).

Note that stacktraces that do not meet `log_level` are discarded in advance. Thanks to this, there's no concern that `trace` or `debug`-level stacktraces being excessively output as `info`-level logs.

You can use this option to exclude all stacktraces from an alerting system if monitoring Fluentd's log files directly. (You don't need this feature if using [@FLUENT\_LOG](https://docs.fluentd.org/logging#capture-fluentd-logs) because stacktraces are not routed into the `@FLUENT_LOG` label.)

### `<source_only_buffer>` section

The temporary buffer setting for [Source Only Mode](https://docs.fluentd.org/deployment/source-only-mode).

#### `flush_thread_count`

| type    | default | version |
| ------- | ------- | ------- |
| integer | 1       | 1.18.0  |

See [Output Plugins - flush\_thread\_count](https://docs.fluentd.org/output#flush_thread_count) for details.

#### `overflow_action`

| type | default             | version |
| ---- | ------------------- | ------- |
| enum | drop\_oldest\_chunk | 1.18.0  |

See [Output Plugins - overflow\_action](https://docs.fluentd.org/output#overflow_action) for details.

#### `path`

| type   | default                                | version |
| ------ | -------------------------------------- | ------- |
| string | nil (use unique path for the instance) | 1.18.0  |

Set this option when recovering buffers ([Source Only Mode - Recovery](https://docs.fluentd.org/source-only-mode#Recovery)).

See [Buffer Plugins - file - path](https://docs.fluentd.org/buffer/file#path) for details.

#### `flush_interval`

| type    | default | version |
| ------- | ------- | ------- |
| integer | 10      | 1.18.0  |

See [Output Plugins - flush\_interval](https://docs.fluentd.org/output#flush_interval) for details.

#### `chunk_limit_size`

| type | default | version |
| ---- | ------- | ------- |
| size | 256MB   | 1.18.0  |

See [Buffer Section Configurations - Buffering Parameters](https://docs.fluentd.org/configuration/buffer-section#buffering-parameters) for details.

#### `total_limit_size`

| type | default | version |
| ---- | ------- | ------- |
| size | 64GB    | 1.18.0  |

See [Buffer Section Configurations - Buffering Parameters](https://docs.fluentd.org/configuration/buffer-section#buffering-parameters) for details.

#### `compress`

| type | default | version |
| ---- | ------- | ------- |
| enum | text    | 1.18.0  |

See [Buffer Section Configurations - Buffering Parameters](https://docs.fluentd.org/configuration/buffer-section#buffering-parameters) for details.

### `Fluent::SystemConfig::Mixin` Methods

#### `.system_config`

Returns `Fluent::SystemConfig` instance.

For code example, please refer to [`api-plugin-base`](https://docs.fluentd.org/plugin-development/api-plugin-base)'s `.system_config` description.

#### `.system_config_override(options = {})`

Overwrites the system configuration.

This is for internal use and plugin testing.

For code example, please refer to [`api-plugin-base`](https://docs.fluentd.org/plugin-development/api-plugin-base)'s `.system_config_override` description.

## Command-Line Options

* `-s`, `--setup [DIR=/etc/fluent]`: Installs sample configuration file to the directory.
* `-c`, `--config PATH`: Specifies the configuration file path. (Default: `/etc/fluent/fluent.conf`)
* `--dry-run`: Verifies the fluentd setup without launching.
* `--show-plugin-config=PLUGIN` (obsolete): Use `fluent-plugin-config-format` command instead.
* `-p`, `--plugin DIR`: Specifies the plugins' directory.
* `-I PATH`: Specifies the library path.
* `-r NAME`: Loads the library.
* `-d`, `--daemon PIDFILE`: Daemonizes the fluentd process.
* `--under-supervisor`: Runs the fluent worker under supervisor (this option is NOT for users).
* `--no-supervisor`: Runs the fluent worker without supervisor.
* `--workers NUM`: Specifies the number of workers under supervisor.
* `--user USER`: Changes user.
* `--group GROUP`: Changes group.
* `--umask UMASK`: Specifies umask to use, in octal form. Defaults to 0.
* `-o`, `--log PATH`: Specifies the log file path.
* `--log-rotate-age AGE`: Specifies the generations to keep rotated log files.
* `--log-rotate-size BYTES`: Sets the byte size to rotate log files.
* `--log-event-verbose`: Enables the events logging during startup/shutdown.
* `-i CONFIG_STRING`, `--inline-config CONFIG_STRING`: Specifies the inlined configuration which is appended to the config file on-the-fly.
* `--emit-error-log-interval SECONDS`: Suppresses the interval (seconds) to emit error logs.
* `--suppress-repeated-stacktrace [VALUE]`: Suppress the repeated stacktrace.
* `--without-source`: Invokes fluentd without input plugins.
* `--with-source-only` (Not supported on Windows): Invokes a fluentd only with input plugins. See [Source Only Mode](https://docs.fluentd.org/deployment/source-only-mode) for details.
* `--use-v1-config`: Uses v1 configuration format (default).
* `--use-v0-config`: Uses v0 configuration format.
* `--strict-config-value`: Parses the configuration values strictly. Invalid numerical or boolean values are rejected. Fluentd raises configuration error exceptions instead of replacing them with `0` or `true` implicitly.
* `-v`, `--verbose`: Increases the verbosity level (`-v`: debug, `-vv`: trace).
* `-q`, `--quiet`: Decreases the verbosity level (`-q`: warn, `-qq`: error).
* `--suppress-config-dump`: Suppresses the configuration dumping on start.
* `-g`, `--gemfile GEMFILE`: Specifies the Gemfile path.
* `-G`, `--gem-path GEM_INSTALL_PATH`: Specifies the Gemfile install path. (Default: `$(dirname $gemfile)/vendor/bundle`)

If this article is incorrect or outdated, or omits critical information, please [let us know](https://github.com/fluent/fluentd-docs-gitbook/issues?state=open). [Fluentd](http://www.fluentd.org/) is an open-source project under [Cloud Native Computing Foundation (CNCF)](https://cncf.io/). All components are available under the Apache 2 License.


---

# Agent Instructions: 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:

```
GET https://docs.fluentd.org/deployment/system-config.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.