---
name: "logger_filters"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/logger_filters"
---

# logger\_filters(3erl)

Filters to use with Logger.

## NAME

logger\_filters - Filters to use with Logger.

## DESCRIPTION

All functions exported from this module can be used as primary or handler filters. See *logger:add\_primary\_filter/2* and *logger:add\_handler\_filter/3* for more information about how filters are added.

Filters are removed with *logger:remove\_primary\_filter/1* and *logger:remove\_handler\_filter/2*.

## EXPORTS

```
domain(LogEvent, Extra) -> logger:filter_return()
```

Types:

LogEvent = logger:log\_event()\
 Extra = {Action, Compare, MatchDomain}\
 Action = log \| stop\
 Compare = super \| sub \| equal \| not\_equal \| undefined\
 MatchDomain = \[atom()\]\

This filter provides a way of filtering log events based on a *domain* field in *Metadata*. This field is optional, and the purpose of using it is to group log events from, for example, a specific functional area. This allows filtering or other specialized treatment in a Logger handler.

A domain field must be a list of atoms, creating smaller and more specialized domains as the list grows longer. The greatest domain is *\[\]*, which comprises all possible domains.

For example, consider the following domains:

```
D1 = [otp]
D2 = [otp, sasl]
```

*D1* is the greatest of the two, and is said to be a super-domain of *D2*. *D2* is a sub-domain *D1*. Both *D1* and *D2* are sub-domains of *\[\]*.

The above domains are used for logs originating from Erlang/OTP. D1 specifies that the log event comes from Erlang/OTP in general, and D2 indicates that the log event is a so called SASL report.

The *Extra* parameter to the *domain/2* function is specified when adding the filter via *logger:add\_primary\_filter/2* or *logger:add\_handler\_filter/3*.

The filter compares the value of the *domain* field in the log event's metadata (*Domain*) against *MatchDomain*. The filter matches if the value of *Compare* is:

- ***sub*:**

  and *Domain* is equal to or a sub-domain of *MatchDomain*, that is, if *MatchDomain* is a prefix of *Domain*.

- ***super*:**

  and *Domain* is equal to or a super-domain of *MatchDomain*, that is, if *Domain* is a prefix of *MatchDomain*.

- ***equal*:**

  and *Domain* is equal to *MatchDomain*.

- ***not\_equal*:**

  and *Domain* differs from *MatchDomain*, or if there is no domain field in metadata.

- ***undefined*:**

  and there is no domain field in metadata. In this case *MatchDomain* must be set to *\[\]*.

If the filter matches and *Action* is *log*, the log event is allowed. If the filter matches and *Action* is *stop*, the log event is stopped.

If the filter does not match, it returns *ignore*, meaning that other filters, or the value of the configuration parameter *filter\_default*, decide if the event is allowed or not.

Log events that do not contain any domain field, match only when *Compare* is equal to *undefined* or *not\_equal*.

Example: stop all events with domain *\[otp, sasl \| \_\]*

```
logger:set_handler_config(h1, filter_default, log). % this is the default
Filter = {fun logger_filters:domain/2, {stop, sub, [otp, sasl]}}.
logger:add_handler_filter(h1, no_sasl, Filter).
ok
```

```
level(LogEvent, Extra) -> logger:filter_return()
```

Types:

LogEvent = logger:log\_event()\
 Extra = {Action, Operator, MatchLevel}\
 Action = log \| stop\
 Operator = neq \| eq \| lt \| gt \| lteq \| gteq\
 MatchLevel = logger:level()\

This filter provides a way of filtering log events based on the log level. It matches log events by comparing the log level with a specified *MatchLevel*

The *Extra* parameter is specified when adding the filter via *logger:add\_primary\_filter/2* or *logger:add\_handler\_filter/3*.

The filter compares the value of the event's log level (*Level*) to *MatchLevel* by calling *logger:compare\_levels(Level, MatchLevel)*. The filter matches if the value of *Operator* is:

- ***neq*:**

  and the compare function returns *lt* or *gt*.

- ***eq*:**

  and the compare function returns *eq*.

- ***lt*:**

  and the compare function returns *lt*.

- ***gt*:**

  and the compare function returns *gt*.

- ***lteq*:**

  and the compare function returns *lt* or *eq*.

- ***gteq*:**

  and the compare function returns *gt* or *eq*.

If the filter matches and *Action* is *log*, the log event is allowed. If the filter matches and *Action* is *stop*, the log event is stopped.

If the filter does not match, it returns *ignore*, meaning that other filters, or the value of the configuration parameter *filter\_default*, will decide if the event is allowed or not.

Example: only allow debug level log events

```
logger:set_handler_config(h1, filter_default, stop).
Filter = {fun logger_filters:level/2, {log, eq, debug}}.
logger:add_handler_filter(h1, debug_only, Filter).
ok
```

```
progress(LogEvent, Extra) -> logger:filter_return()
```

Types:

LogEvent = logger:log\_event()\
 Extra = log \| stop\

This filter matches all progress reports from *supervisor* and *application\_controller*.

If *Extra* is *log*, the progress reports are allowed. If *Extra* is *stop*, the progress reports are stopped.

The filter returns *ignore* for all other log events.

```
remote_gl(LogEvent, Extra) -> logger:filter_return()
```

Types:

LogEvent = logger:log\_event()\
 Extra = log \| stop\

This filter matches all events originating from a process that has its group leader on a remote node.

If *Extra* is *log*, the matching events are allowed. If *Extra* is *stop*, the matching events are stopped.

The filter returns *ignore* for all other log events.

## SEE ALSO

*[logger(3erl)](/logger/3erl.md)*