# Throttle

The *Throttle* filter sets the average `Rate` of messages per `Interval`, based on the leaky bucket and sliding window algorithm. In case of flooding, it will leak at a certain rate.

## Configuration parameters

The plugin supports the following configuration parameters:

| Key            | Value Format | Description                                                                            |
| -------------- | ------------ | -------------------------------------------------------------------------------------- |
| `Rate`         | `Integer`    | Amount of messages for the time.                                                       |
| `Window`       | `Integer`    | Amount of intervals to calculate average over. Default: `5`.                           |
| `Interval`     | `String`     | Time interval, expressed in `sleep` format. For example, `3s`, `1.5m`, `0.5h`.         |
| `Print_Status` | `Bool`       | Whether to print status messages with current rate and the limits to information logs. |

## Functional description

Using the following configuration:

```
Rate 5
Window 5
Interval 1s
```

You would receive 1 message in the first second, 3 messages second, and 5 third. Disregard that Window is actually 5, because the configuration uses `slow` start to prevent flooding during the startup.

```
+-------+-+-+-+
|1|3|5| | | | |
+-------+-+-+-+
|  3  |         average = 3, and not 1.8 if you calculate 0 for last 2 panes.
+-----+
```

But as soon as you reach `Window size * Interval`, you will have true sliding window with aggregation over complete window.

```
+-------------+
|1|3|5|7|3|4| |
+-------------+
  |  4.4    |
  ----------+
```

When the average over window is more than `Rate`, Fluent Bit starts dropping messages, so the following:

```
+-------------+
|1|3|5|7|3|4|7|
+-------------+
    |   5.2   |
    +---------+
```

will become:

```
+-------------+
|1|3|5|7|3|4|6|
+-------------+
    |   5     |
    +---------+
```

The last pane of the window was overwritten and 1 message was dropped.

### `Interval` versus `Window` size

You might notice it's possible to configure the `Interval` of the `Window` shift. It's counterintuitive, but there is a difference between the two previous examples:

```
Rate 60
Window 5
Interval 1m
```

and

```
Rate 1
Window 300
Interval 1s
```

Even though both examples will allow maximum `Rate` of 60 messages per minute, the first example might get all 60 messages within first second, and will drop all the rest for the entire minute:

```
XX        XX        XX
XX        XX        XX
XX        XX        XX
XX        XX        XX
XX        XX        XX
XX        XX        XX
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
```

While the second example won't allow more than 1 message per second every second, making output rate more smooth:

```
  X    X     X    X    X    X
XXXX XXXX  XXXX XXXX XXXX XXXX
+-+-+-+-+-+--+-+-+-+-+-+-+-+-+-+
```

Fluent Bit might drop some data if the rate is ragged. Use bigger intervals and rates for streams of rare but important events, while keeping `Window` bigger and `Interval` smaller for constantly intensive inputs.

### Command line

It's suggested to use a configuration file.

The following command will load the Tail plugin and read the content of the `lines.txt` file. Then, the Throttle filter will apply a rate limit and only pass the records which are read below the `rate`:

```shell
fluent-bit -i tail -p 'path=lines.txt' -F throttle -p 'rate=1' -m '*' -o stdout
```

### Configuration file

{% tabs %}
{% tab title="fluent-bit.yaml" %}

```yaml
pipeline:
  inputs:
    - name: tail
      path: lines.txt

  filters:
    - name: throttle
      match: '*'
      rate: 1000
      window: 300
      interval: 1s

  outputs:
    - name: stdout
      match: '*'
```

{% endtab %}

{% tab title="fluent-bit.conf" %}

```
[INPUT]
  Name   tail
  Path   lines.txt

[FILTER]
  Name     throttle
  Match    *
  Rate     1000
  Window   300
  Interval 1s

[OUTPUT]
  Name   stdout
  Match  *
```

{% endtab %}
{% endtabs %}

This example will pass 1000 messages per second in average over 300 seconds.


---

# 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.fluentbit.io/manual/4.0/data-pipeline/filters/throttle.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.