# Configure Sidecar Filters

This guide will walk through how to enable and configure filters on the Grey Matter sidecar. To see the many filter options, check out the [filters documentation](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters).

Filters can be set on any service that is configured in the mesh. This guide will be an overview of the general steps to enabling a filter, and will use the [Grey Matter Observables filter](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters/http/gm-observables) on the Grey Matter SLO service as an example. There are several existing guides for configuring and setting specific filters - [fault injection](https://greymatter.gitbook.io/grey-matter-documentation/1.3/guides/fabric-guides/fault-injection), [rate limiting](https://greymatter.gitbook.io/grey-matter-documentation/1.3/guides/fabric-guides/rate-limit-deployment), and the [OIDC filter chain](https://greymatter.gitbook.io/grey-matter-documentation/1.3/guides/fabric-guides/oidc).

{% hint style="success" %}
The **Grey Matter Sidecar's** **functionality** allows for deep request and response lifecycle observability in your network. We've extended Envoy's filters with in-house Go libraries.
{% endhint %}

## Prerequisites

1. An existing Grey Matter deployment running on Kubernetes ([tutorial](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/installation-kubernetes))
2. `kubectl` or `oc` setup with access to the cluster
3. `greymatter` cli [setup](https://greymatter.gitbook.io/grey-matter-documentation/1.3/installation/commands-cli) with access to the deployment

## Steps

### Overview

There are two options for setting filters on a Grey Matter sidecar. They can either be set on a [listener object](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/listener) for your service, or on its [proxy object](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/proxy). Setting the filters at the listener level is recommended as it allows for more clear and specific granularity to the behavior of the filters. We will set at the listener level in this guide. Applying filters to the proxy object for a sidecar will enable the filter for **every** listener attached to it.

Filters can be set at either the [HTTP](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters/http) or the [network](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters/network) level. This guide will walk through setting an HTTP filter.

### 1. Generate filter configuration

To generate the configuration for a filter, get its **active filter name** from the [list of available filters](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters/http#available-filter-summary).

> Note: For enabling a network filter, the available filters and their active filter names can be found [here](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/filters/network#available-network-filters).

The active filter name for the Grey Matter Observables filter is `gm.observables`. It's corresponding configuration name will then be `gm_observables`. This pattern is consistent for all filters.

The configuration will be different for each filter, see the reference docs for the specific configuration options. For this guide, we will set the following configuration for observables:

```javascript
"gm_observables": {
  "emitFullResponse": false,
  "useKafka": false,
  "topic": "example-topic",
  "eventTopic": "greymatter"
}
```

Since `useKafka` is false, the observables will be emitted to stdout, and we will be able to see them in the sidecar logs to test that the filter has been enabled.

### 2. Enable the filter

There are two updates to a listener object to enable a filter, adding the active filter name to the `active_http_filters` list, and adding it's configuration to the `http_filters` map object.

> Note: For network filters, you would make the corresponding changes to `active_network_filters` and `network_filters` instead. For setting filters on a proxy object, you would make the corresponding changes to `active_proxy_filters` and `proxy_filters` instead.

Run the following to edit the SLO ingress listener:

```bash
greymatter edit listener listener-slo
```

And add the active filter name, `"gm.observables"`, to the `active_http_filters` field, so that it looks like:

```javascript
"active_http_filters": [
  ...
  "gm.observables"
],
```

Then, we will add the configuration generated in [step 1](#1-generate-filter-configuration) to the `http_filters` map, with key `gm_observables`, the listener should look like:

```javascript
{
  "active_http_filters": [
    ...
    "gm.observables"
  ],
  "http_filters": {
    ...
    "gm_observables": {
      "emitFullResponse": false,
      "useKafka": false,
      "topic": "example-topic",
      "eventTopic": "greymatter"
    }
  },
  "listener_key": "listener-slo",
  ...
}
```

Once the listener object looks like the above, save the configuration. If you don't see any errors from the CLI, the filter should be enabled.

### 3. Verify

To verify that the filter has been enabled, follow the sidecar logs:

```bash
kubectl logs -l greymatter.io/control=slo -c sidecar -f
```

Then make a request to the SLO service in your browser - you can hit the docs at path `/services/slo/latest`. In the logs you will see the observable:

```bash
{"eventId":"109253e7-3975-11eb-b12f-82ca5b8a7000","eventChain":["109253e7-3975-11eb-b12f-82ca5b8a7000"],"schemaVersion":"1.0","originatorToken":["CN=quickstart,OU=Engineering,O=Decipher Technology Studios,L=Alexandria,ST=Virginia,C=US","CN=quickstart,OU=Engineering,O=Decipher Technology Studios,L=Alexandria,ST=Virginia,C=US"],"eventType":"example-topic","timestamp":1607446051, ...
```

This shows a successful filter configuration!

### Modifying and disabling

Any available filter can be configured in this way.

To make any configuration modifications, you can edit the listener (or proxy) object directly, once the object is saved, the changes will take affect.

To disable a filter at any time, you can delete the active filter name from the `active_*_filters` list. The configuration will remain in `*_filters` so you can quickly turn it on/off if necessary. If you don't plan to re-enable the filter at any time, you can delete both the name from the `active_*_filters` list, and the configuration from the `*_filters` map.

## Questions

{% hint style="success" %}
**Need help with your installation?**

Create an account at [Grey Matter Support](https://support.greymatter.io/support/home) to reach our team.
{% endhint %}