logger_filters(3erl)

📦
version 25.3.2.8 · 5 versions
, in ubuntu noble

🌸 NAME 🌸

Okay bestie, welcome to logger_filters(3erl) — the Erlang Module Definition page for the logger_filters module. Filters to use with Logger. 💅

✨ DESCRIPTION ✨

Every function exported from this module can be used as a primary filter or a handler filter. See logger:add_primary_filter/2 and logger:add_handler_filter/3 for more info on how filters get 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 is the way to filter log events based on a domain field in Metadata. That field is optional, and the whole point of using it is to group log events from, like, a specific functional area. That way a Logger handler can filter them or give them specialized treatment. ✨

A domain field has to be a list of atoms, and the domains get smaller and more specialized as the list grows longer. The greatest domain is [], which covers all possible domains. No cap.

For example, consider these domains:

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

D1 is the greatest of the two and is called a super-domain of D2. D2 is a sub-domain of D1. Both D1 and D2 are sub-domains of [].

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

The Extra parameter to the domain/2 function is specified when you add 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 is the way to filter 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 you add 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)

💖 Big cute sign-off: this page is brought to you by Ericsson AB, version kernel 8.5.4.2, and the manual page is logger_filters(3erl). The footer doesn’t print a date, so no invented date bestie — just facts and vibes. 🫶✨

📦 where this page comes from