<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>2018</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>logger_filters</title>
<prepared></prepared>
<responsible></responsible>
<docno></docno>
<approved></approved>
<checked></checked>
<date></date>
<rev>A</rev>
<file>logger_filters.xml</file>
</header>
<module>logger_filters</module>
<modulesummary>Filters to use with logger.</modulesummary>
<description>
<p>Filters to use with logger. All functions exported from this
module can be used as logger or handler
filters. See <seealso marker="logger#add_logger_filter-2">
<c>logger:add_logger_filter/2</c></seealso>
and <seealso marker="logger#add_handler_filter-3">
<c>logger:add_handler_filter/3</c></seealso>
for more information about how filters are added.</p>
</description>
<funcs>
<func>
<name name="domain" arity="2"/>
<fsummary>Filter log events based on the domain field in metadata.</fsummary>
<desc>
<p>This filter provides a way of filtering log events based on a
<c>domain</c> field <c>Metadata</c>.</p>
<p>The <c><anno>Extra</anno></c> parameter is specified when
adding the filter
via <seealso marker="logger#add_logger_filter-2">
<c>logger:add_logger_filter/2</c></seealso>
or <seealso marker="logger#add_handler_filter-3">
<c>logger:add_handler_filter/3</c></seealso>.</p>
<p>The filter compares the value of the <c>domain</c> field
in the log event's metadata (<c>Domain</c>)
to <c><anno>MatchDomain</anno></c> as follows:</p>
<taglist>
<tag><c><anno>Compare</anno> = starts_with</c></tag>
<item><p>The filter matches if <c>MatchDomain</c> is a prefix
of <c>Domain</c>.</p></item>
<tag><c><anno>Compare</anno> = prefix_of</c></tag>
<item><p>The filter matches if <c>Domain</c> is a prefix
of <c>MatchDomain</c>.</p></item>
<tag><c><anno>Compare</anno> = equals</c></tag>
<item><p>The filter matches if <c>Domain</c> is equal
to <c>MatchDomain</c>.</p></item>
<tag><c><anno>Compare</anno> = no_domain</c></tag>
<item><p>The filter matches if there is no domain field in
metadata. In this case <c><anno>MatchDomain</anno></c> shall
be <c>[]</c>.</p></item>
</taglist>
<p>If the filter matches and <c><anno>Action</anno> =
log</c>, the log event is allowed. If the filter matches
and <c><anno>Action</anno> = stop</c>, the log event is
stopped.</p>
<p>If the filter does not match, it returns <c>ignore</c>,
meaning that other filters, or the value of the
configuration parameter <c>filter_default</c>, will decide
if the event is allowed or not.</p>
<p>Log events that do not contain any domain field, will
only match when <c><anno>Compare</anno> = no_domain</c>.</p>
<p>Example: stop all events with
domain <c>[beam,erlang,otp,sasl|_]</c></p>
<code>
logger:set_handler_config(h1,filter_default,log). % this is the default
Filter = {fun logger_filters:domain/2,{stop,starts_with,[beam,erlang,otp,sasl]}}.
logger:add_handler_filter(h1,no_sasl,Filter).
ok</code>
</desc>
</func>
<func>
<name name="level" arity="2"/>
<fsummary>Filter log events based on the log level.</fsummary>
<desc>
<p>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 predefined <c>MatchLevel</c></p>
<p>The <c><anno>Extra</anno></c> parameter is specified when
adding the filter
via <seealso marker="logger#add_logger_filter-2">
<c>logger:add_logger_filter/2</c></seealso>
or <seealso marker="logger#add_handler_filter-3">
<c>logger:add_handler_filter/3</c></seealso>.</p>
<p>The filter compares the value of the event's log level
(<c>Level</c>) to <c><anno>MatchLevel</anno></c> by
calling <seealso marker="logger#compare_levels-2">
<c>logger:compare_levels(Level,MatchLevel) -> CmpRet</c></seealso>. It
matches the event if:</p>
<list>
<item><c>CmpRet = eq</c> and <c><anno>Operator</anno> =
eq | lteq | gteq</c></item>
<item><c>CmpRet = lt</c> and <c><anno>Operator</anno> =
lt | lteq | neq</c></item>
<item><c>CmpRet = gt</c> and <c><anno>Operator</anno> =
gt | gteq | neq</c></item>
</list>
<p>If the filter matches and <c><anno>Action</anno> =
log</c>, the log event is allowed. If the filter matches
and <c><anno>Action</anno> = stop</c>, the log event is
stopped.</p>
<p>If the filter does not match, it returns <c>ignore</c>,
meaning that other filters, or the value of the
configuration parameter <c>filter_default</c>, will decide
if the event is allowed or not.</p>
<p>Example: only allow debug level log events</p>
<code>
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</code>
</desc>
</func>
<func>
<name name="progress" arity="2"/>
<fsummary>Filter progress reports from supervisor and application_controller.</fsummary>
<desc>
<p>This filter matches all progress reports
from <c>supervisor</c> and <c>application_controller</c>.</p>
<p>If <c><anno>Extra</anno> = log</c>, the progress reports
are allowed. If <c><anno>Extra</anno> = stop</c>, the
progress reports are stopped.</p>
<p>The filter returns <c>ignore</c> for all other log events.</p>
</desc>
</func>
<func>
<name name="remote_gl" arity="2"/>
<fsummary>Filter events with group leader on remote node.</fsummary>
<desc>
<p>This filter matches all events originating from a process
that has its group leader on a remote node.</p>
<p>If <c><anno>Extra</anno> = log</c>, the matching events
are allowed. If <c><anno>Extra</anno> = stop</c>, the
matching events are stopped.</p>
<p>The filter returns <c>ignore</c> for all other log events.</p>
</desc>
</func>
</funcs>
</erlref>
