<?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 since="OTP 21.0">logger_filters</module>
  <modulesummary>Filters to use with Logger.</modulesummary>

  <description>
    <p>All functions exported from this module can be used as primary
      or handler
      filters. See <seemfa marker="logger#add_primary_filter/2">
	<c>logger:add_primary_filter/2</c></seemfa>
      and <seemfa marker="logger#add_handler_filter/3">
	<c>logger:add_handler_filter/3</c></seemfa> for more information
      about how filters are added.</p>
    <p>Filters are removed with <seemfa marker="logger#remove_primary_filter/1">
	<c>logger:remove_primary_filter/1</c></seemfa>
      and <seemfa marker="logger#remove_handler_filter/2">
	<c>logger:remove_handler_filter/2</c></seemfa>.</p>
  </description>

  <funcs>
    <func>
      <name name="domain" arity="2" since="OTP 21.0"/>
      <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 in <c>Metadata</c>. 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.</p>

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

	<p>For example, consider the following domains:</p>
	<pre>
D1 = [otp]
D2 = [otp, sasl]</pre>

	<p><c>D1</c> is the greatest of the two, and is said to be a
	  super-domain of <c>D2</c>. <c>D2</c> is a
	  sub-domain <c>D1</c>. Both <c>D1</c> and <c>D2</c> are
	  sub-domains of <c>[]</c>.</p>

	<p>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 <seeguide marker="logger_chapter#sasl_reports">SASL
	  report</seeguide>.</p>

	<p>The <c><anno>Extra</anno></c> parameter to
	  the <c>domain/2</c> function is specified when adding the
	  filter via <seemfa marker="logger#add_primary_filter/2">
	    <c>logger:add_primary_filter/2</c></seemfa>
	  or <seemfa marker="logger#add_handler_filter/3">
	    <c>logger:add_handler_filter/3</c></seemfa>.</p>

	<p>The filter compares the value of the <c>domain</c> field in
	  the log event's metadata (<c>Domain</c>) against
	  <c><anno>MatchDomain</anno></c>. The filter matches if the
	  value of <c>Compare</c> is:</p>

	<taglist>
	  <tag><c>sub</c></tag>
	  <item>
	    <p>and <c>Domain</c> is equal to or a sub-domain
	      of <c>MatchDomain</c>, that is, if <c>MatchDomain</c> is
	      a prefix of <c>Domain</c>.</p>
	  </item>
	  <tag><c>super</c></tag>
	  <item>
	    <p>and <c>Domain</c> is equal to or a super-domain
	      of <c>MatchDomain</c>, that is, if <c>Domain</c> is a
	      prefix of <c>MatchDomain</c>.</p>
	  </item>
	  <tag><c>equal</c></tag>
	  <item>
	    <p>and <c>Domain</c> is equal to <c>MatchDomain</c>.</p>
	  </item>
	  <tag><c>not_equal</c></tag>
	  <item>
	    <p>and <c>Domain</c> differs from <c>MatchDomain</c>, or
	      if there is no domain field in metadata.</p>
	  </item>
	  <tag><c>undefined</c></tag>
	  <item>
	    <p>and there is no domain field in metadata. In this
	      case <c><anno>MatchDomain</anno></c> must be set
	      to <c>[]</c>.</p>
	  </item>
	</taglist>

        <p>If the filter matches and <c><anno>Action</anno></c> is
          <c>log</c>, the log event is allowed. If the filter matches
          and <c><anno>Action</anno></c> is <c>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>, decide if the
	  event is allowed or not.</p>

	<p>Log events that do not contain any domain field, match only
	  when <c><anno>Compare</anno></c> is equal
	  to <c>undefined</c> or <c>not_equal</c>.</p>

	<p>Example: stop all events with domain <c>[otp,
	  sasl | _]</c></p>

	<code>
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</code>
      </desc>
    </func>

    <func>
      <name name="level" arity="2" since="OTP 21.0"/>
      <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 specified <c>MatchLevel</c></p>

	  <p>The <c><anno>Extra</anno></c> parameter is specified when
	    adding the filter
	    via <seemfa marker="logger#add_primary_filter/2">
	      <c>logger:add_primary_filter/2</c></seemfa>
	    or <seemfa marker="logger#add_handler_filter/3">
	      <c>logger:add_handler_filter/3</c></seemfa>.</p>

	  <p>The filter compares the value of the event's log level
	    (<c>Level</c>) to <c><anno>MatchLevel</anno></c> by
	    calling <seemfa marker="logger#compare_levels/2">
	      <c>logger:compare_levels(Level, MatchLevel)</c></seemfa>.
	    The filter matches if the value
	    of <c><anno>Operator</anno></c> is:</p>

	  <taglist>
	    <tag><c>neq</c></tag>
	    <item><p>and the compare function returns <c>lt</c>
		or <c>gt</c>.</p></item>
	    <tag><c>eq</c></tag>
	    <item><p>and the compare function returns <c>eq</c>.</p></item>
	    <tag><c>lt</c></tag>
	    <item><p>and the compare function returns <c>lt</c>.</p></item>
	    <tag><c>gt</c></tag>
	    <item><p>and the compare function returns <c>gt</c>.</p></item>
	    <tag><c>lteq</c></tag>
	    <item><p>and the compare function returns <c>lt</c>
		or <c>eq</c>.</p></item>
	    <tag><c>gteq</c></tag>
	    <item><p>and the compare function returns <c>gt</c>
		or <c>eq</c>.</p></item>
	  </taglist>

          <p>If the filter matches and <c><anno>Action</anno></c> is
            <c>log</c>, the log event is allowed. If the filter
            matches and <c><anno>Action</anno></c> is <c>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" since="OTP 21.0"/>
      <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></c> is <c>log</c>, the progress
	    reports are allowed. If <c><anno>Extra</anno></c>
	    is <c>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" since="OTP 21.0"/>
      <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></c> is <c>log</c>, the matching
	    events are allowed. If <c><anno>Extra</anno></c>
	    is <c>stop</c>, the matching events are stopped.</p>

	  <p>The filter returns <c>ignore</c> for all other log events.</p>
      </desc>
    </func>

  </funcs>

  <section>
    <title>See Also</title>
    <p>
      <seeerl marker="logger"><c>logger(3)</c></seeerl>
    </p>
  </section>
</erlref>


