# Filter Plugins

Fluentd has nine (9) types of plugins:

* [Input](https://docs.fluentd.org/input)
* [Parser](https://docs.fluentd.org/parser)
* [Filter](https://docs.fluentd.org/filter)
* [Output](https://docs.fluentd.org/output)
* [Formatter](https://docs.fluentd.org/formatter)
* [Storage](https://docs.fluentd.org/storage)
* [Service Discovery](https://docs.fluentd.org/service_discovery)
* [Buffer](https://docs.fluentd.org/buffer)
* [Metrics](https://docs.fluentd.org/metrics)

This article gives an overview of the Filter Plugin.

## Overview

Filter plugins enable Fluentd to modify event streams. Some use cases are:

1. Filtering out events by grepping the value of one or more fields.
2. Enriching events by adding new fields.
3. Deleting or masking certain fields for privacy and compliance.

## How To Use

It is used with the `<filter>` directive:

```
<filter foo.bar>
  @type grep
  regexp1 message cool
</filter>
```

The above directive matches events with the tag `foo.bar`, and if the `message` field's value contains `cool`, the events go through the rest of the configuration.

Like the `<match>` directive for output plugins, `<filter>` matches against a tag. Once the event is processed by the filter, the event proceeds through the configuration top-down. Hence, if there are multiple filters for the same tag, they are applied in descending order. Hence, in the following example:

```
<filter foo.bar>
  @type grep
  regexp1 message cool
</filter>

<filter foo.bar>
  @type record_transformer
  <record>
    hostname "#{Socket.gethostname}"
  </record>
</filter>
```

Only the events whose `message` field contain `cool` get the new field `hostname` with the machine's hostname as its value.

Users can create their own custom plugins with a bit of Ruby. See [this section](https://docs.fluentd.org/plugin-development#filter-plugins) for more information.

## Filter Chain Optimization

If you have multiple filters in the pipeline, fluentd tries to optimize filter calls to improve the performance. The condition for optimization is that all plugins in the pipeline use the `filter` method. If the plugin which uses `filter_stream` exists, chain optimization is disabled.

If you see the following message in the log, the optimization is disabled:

```
disable filter chain optimization because [Fluent::Plugin::XXXFilter] uses `#filter_stream` method
```

This is not a critical log message and you can ignore it.

## List of Filter Plugins

* [`grep`](https://docs.fluentd.org/filter/grep)
* [`record_transformer`](https://docs.fluentd.org/filter/record_transformer)
* [`filter_stdout`](https://docs.fluentd.org/filter/stdout)

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/filter.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.