# exec

The `out_exec` TimeSliced Output plugin passes events to an external program. The program receives the path to a file containing the incoming events as its last argument. The file format is tab-separated values (TSV) by default.

It is included in Fluentd's core.

## Example Configuration

```
<match pattern>
  @type exec
  command cmd arg arg
  <format>
    @type tsv
    keys k1,k2,k3
  </format>
  <inject>
    tag_key k1
    time_key k2
    time_format %Y-%m-%d %H:%M:%S
  </inject>
</match>
```

Please see the [Configuration File](https://docs.fluentd.org/configuration/config-file) article for the basic structure and syntax of the configuration file.

## Example: Running FizzBuzz Against Data Stream

This example illustrates how to run FizzBuzz with `out_exec`.

We assume that the input file is specified by the last argument in the command line (`ARGV[-1]`). The following script `fizzbuzz.py` runs [FizzBuzz](http://en.wikipedia.org/wiki/Fizz_buzz) against the new-line delimited sequence of natural numbers (1, 2, 3...) and writes the output to `foobar.out`:

```
#!/usr/bin/env python
import sys
input = file(sys.argv[-1])
output = file("foobar.out", "a")
for line in input:
    fizzbuzz = int(line.split("\t")[0])
    s = ''
    if fizzbuzz%3 == 0:
        s += 'fizz'
    if fizzbuzz%5 == 0:
        s += 'buzz'
    if len(s) > 0:
        output.write(s+"\n")
    else:
        output.write(str(fizzbuzz)+"\n")
output.close
```

Note that this program is written in Python. For `out_exec` (as well as `out_exec_filter` and `in_exec`), **the program can be written in any language, not just Ruby.**

Then, configure Fluentd as follows:

```
<source>
  @type forward
</source>
<match fizzbuzz>
  @type exec
  command python /path/to/fizzbuzz.py
  <buffer>
    @type file
    path /path/to/buffer_path
    flush_interval 5s # for debugging/checking
  </buffer>
  <format>
    @type tsv
    keys fizzbuzz
  </format>
</match>
```

The `@type tsv` and `keys fizzbuzz` in `<format>` tells Fluentd to extract the `fizzbuzz` field and output it as TSV. This simple example has a single key, but you can of course extract multiple fields and use `format json` to output newline-delimited JSON.

The intermediate TSV is at `/path/to/buffer_path`, and the command `python /path/to/fizzbuzz.py /path/to/buffer_path` is run. This is why in `fizzbuzz.py`, it is reading the file at `sys.argv[-1]`.

If you start Fluentd and run this command:

```
$ for i in `seq 15`; do echo "{\"fizzbuzz\":$i}" | fluent-cat fizzbuzz; done
```

Then, after 5 seconds, you get a file named `foobar.out`:

```
$ cat foobar.out
1
2
fizz
4
buzz
fizz
7
8
fizz
buzz
11
fizz
13
14
fizzbuzz
```

## Supported Modes

* Asynchronous

See [Output Plugin Overview](https://docs.fluentd.org/output) for more details.

## Plugin Helpers

* [`inject`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-inject)
* [`formatter`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-formatter)
* [`compat_parameters`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-compat_parameters)
* [`child_process`](https://docs.fluentd.org/plugin-helper-overview/api-plugin-helper-child_process)

## Parameters

[Common Parameters](https://docs.fluentd.org/configuration/plugin-common-parameters)

### `@type`

The value must be `exec`.

### `command`

| type   | default | version |
| ------ | ------- | ------- |
| string | Nothing | 0.14.0  |

The command (program) to execute. The `exec` plugin passes the path of flushed buffer chunk as the last argument.

If you set `command` parameter like this:

```
command cmd arg arg
```

The actual command execution is:

```
cmd arg arg /path/to/file
```

If `cmd` does not exist in PATH, you need to specify the absolute path, e.g. `/path/to/cmd`.

### `command_timeout`

| type | default | version |
| ---- | ------- | ------- |
| time | 270     | 0.14.9  |

Command (program) execution timeout.

### `<format>` Section

See [Format Section](https://docs.fluentd.org/configuration/format-section) for more details.

#### `@type`

| type   | default | version |
| ------ | ------- | ------- |
| string | tsv     | 0.14.9  |

The format used to map the incoming events to the program input.

Overwrites the default value in this plugin.

### `<inject>` Section

See [Inject Section](https://docs.fluentd.org/configuration/inject-section) for more details.

#### `time_type`

| type   | default | version |
| ------ | ------- | ------- |
| string | string  | 0.14.9  |

Overwrites the default value in this plugin.

#### `localtime`

| type | default | version |
| ---- | ------- | ------- |
| bool | false   | 0.14.9  |

Overwrites the default value in this plugin.

### `<buffer>` Section

See [Buffer Section](https://docs.fluentd.org/configuration/buffer-section) for more details.

#### `delayed_commit_timeout`

| type | default | version |
| ---- | ------- | ------- |
| time | 300     | 0.14.9  |

Overwrites the default value in this plugin.

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/output/exec.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.