···7575<a id="md:filtering-by-label" class="tsd-anchor"></a><h4 class="tsd-anchor-link">Filtering By Label<a href="#md:filtering-by-label" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h4><p>Logs can be filtered by labels similar to how <a href="https://github.com/debug-js/debug" target="_blank" class="external">debug-js</a> works.</p>
7676<p>By default <em>no</em> filtering is done. Your child loggers follow the Pino Child Logger behavior of inherting parent log level.</p>
7777<p>Using either <code>LOG_FILTER_ENABLE</code> or <code>LOG_FILTER_DISABLE</code> you can enable or disable a child logger and it's children.</p>
7878-<pre><code class="ts"><br/><span class="hl-7">/*</span><br/><span class="hl-7"> * process.env.LOG_FILTER_ENABLE = 'Third:Fourth,Second:*:Foo,Bar'</span><br/><span class="hl-7"> */</span><br/><br/><span class="hl-2">import</span><span class="hl-1"> {</span><span class="hl-0">loggerApp</span><span class="hl-1">, </span><span class="hl-0">childLogger</span><span class="hl-1">} </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-3">'@foxxmd/logging'</span><span class="hl-1">;</span><br/><br/><span class="hl-0">logger</span><span class="hl-1"> = </span><span class="hl-6">loggerApp</span><span class="hl-1">();</span><br/><span class="hl-0">logger</span><span class="hl-1">.</span><span class="hl-6">debug</span><span class="hl-1">(</span><span class="hl-3">'Test'</span><span class="hl-1">);</span><br/><span class="hl-7">// [2024-03-07 11:27:41.944 -0500] DEBUG: Test</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild1</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">logger</span><span class="hl-1">, </span><span class="hl-3">'First'</span><span class="hl-1">);</span><br/><span class="hl-0">nestedChild1</span><span class="hl-1">.</span><span class="hl-6">debug</span><span class="hl-1">(</span><span class="hl-3">'I am nested one level'</span><span class="hl-1">);</span><br/><span class="hl-7">// [2024-03-07 11:27:41.945 -0500] DEBUG: [First] I am nested one level</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild2</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild1</span><span class="hl-1">, [</span><span class="hl-3">'Second'</span><span class="hl-1">, </span><span class="hl-3">'Third'</span><span class="hl-1">], { </span><span class="hl-0">level:</span><span class="hl-1"> </span><span class="hl-3">'silent'</span><span class="hl-1"> });</span><br/><span class="hl-0">nestedChild2</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do not log because of set level and not enabled by filter'</span><span class="hl-1">);</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild3</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild2</span><span class="hl-1">, [</span><span class="hl-3">'Fourth'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild3</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Third:Fourth'</span><span class="hl-1">);</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild4</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild3</span><span class="hl-1">, [</span><span class="hl-3">'Foo'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild4</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Second:*:Foo'</span><span class="hl-1">);</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild5</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild4</span><span class="hl-1">, [</span><span class="hl-3">'Bar'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild5</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Bar'</span><span class="hl-1">);</span>
7878+<pre><code class="ts"><br/><span class="hl-7">/*</span><br/><span class="hl-7"> * process.env.LOG_FILTER_ENABLE = 'Third:Fourth,Second:*:Foo,Bar'</span><br/><span class="hl-7"> */</span><br/><br/><span class="hl-2">import</span><span class="hl-1"> {</span><span class="hl-0">loggerApp</span><span class="hl-1">, </span><span class="hl-0">childLogger</span><span class="hl-1">} </span><span class="hl-2">from</span><span class="hl-1"> </span><span class="hl-3">'@foxxmd/logging'</span><span class="hl-1">;</span><br/><br/><span class="hl-0">logger</span><span class="hl-1"> = </span><span class="hl-6">loggerApp</span><span class="hl-1">();</span><br/><span class="hl-0">logger</span><span class="hl-1">.</span><span class="hl-6">debug</span><span class="hl-1">(</span><span class="hl-3">'Test'</span><span class="hl-1">);</span><br/><span class="hl-7">// [2024-03-07 11:27:41.944 -0500] DEBUG: Test</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild1</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">logger</span><span class="hl-1">, </span><span class="hl-3">'First'</span><span class="hl-1">);</span><br/><span class="hl-0">nestedChild1</span><span class="hl-1">.</span><span class="hl-6">debug</span><span class="hl-1">(</span><span class="hl-3">'I am nested one level'</span><span class="hl-1">);</span><br/><span class="hl-7">// [2024-03-07 11:27:41.945 -0500] DEBUG: [First] I am nested one level</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild2</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild1</span><span class="hl-1">, [</span><span class="hl-3">'Second'</span><span class="hl-1">, </span><span class="hl-3">'Third'</span><span class="hl-1">], { </span><span class="hl-0">level:</span><span class="hl-1"> </span><span class="hl-3">'silent'</span><span class="hl-1"> });</span><br/><span class="hl-0">nestedChild2</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do not log because of set level and not enabled by filter'</span><span class="hl-1">);</span><br/><br/><span class="hl-7">// without LOG_FILTER_ENABLE from above set, the below logging would be silent</span><br/><span class="hl-7">// because they inherit the level from their parent</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild3</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild2</span><span class="hl-1">, [</span><span class="hl-3">'Fourth'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild3</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Third:Fourth'</span><span class="hl-1">);</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild4</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild3</span><span class="hl-1">, [</span><span class="hl-3">'Foo'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild4</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Second:*:Foo'</span><span class="hl-1">);</span><br/><br/><span class="hl-4">const</span><span class="hl-1"> </span><span class="hl-5">nestedChild5</span><span class="hl-1"> = </span><span class="hl-6">childLogger</span><span class="hl-1">(</span><span class="hl-0">nestedChild4</span><span class="hl-1">, [</span><span class="hl-3">'Bar'</span><span class="hl-1">]);</span><br/><span class="hl-0">nestedChild5</span><span class="hl-1">.</span><span class="hl-6">info</span><span class="hl-1">(</span><span class="hl-3">'I do log because of filter Bar'</span><span class="hl-1">);</span>
7979</code><button type="button">Copy</button></pre>
80808181+<p>The minimum level a child logger is "enabled" to is ENV <code>LOG_FILTER_ENABLE_LEVEL</code> or <code>trace</code>, by default. It can also be specified by passing <code>labelEnableLevel</code> to childLogger options.</p>
8282+<p>The minimum level a child logger is "disabled" to is ENV <code>LOG_FILTER_DISABLE_LEVEL</code> or <code>silent</code>, by default. It can also be specified by passing <code>labelDisableLevel</code> to childLogger options.</p>
8383+<p>There are also options for passing your own function to determine if a child logger should be enabled or disabled. See <a href="https://foxxmd.github.io/logging/functions/index.childLogger.html" target="_blank" class="external"><code>childLogger</code></a> docs for full a full reference.</p>
8484+<p>A caveat to be aware of: <strong>enable/disable by filter is evaluated once, when <code>childLogger</code> is instantiated.</strong> This means:</p>
8585+<ul>
8686+<li>Only the labels added by <code>childLogger</code> insantiation are applicable. Labels added during logging, IE <code>logger.info({labels: ['Runtime']}, "a log")</code>, are not considered.</li>
8787+<li>Labels that are functions are evaluated <strong>once</strong>, when <code>childLogger</code> is instantiated</li>
8888+<li>Changing the <code>LOG_FILTER_*</code> envs after a childLogger is created will have no effect on it</li>
8989+</ul>
8190<a id="md:serializing-objects-and-errors" class="tsd-anchor"></a><h3 class="tsd-anchor-link">Serializing Objects and Errors<a href="#md:serializing-objects-and-errors" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24"><use href="assets/icons.svg#icon-anchor"></use></svg></a></h3><p>Passing an object or array as the first argument to the logger will cause the object to be JSONified and pretty printed below the log message</p>
8291<pre><code class="ts"><span class="hl-0">logger</span><span class="hl-1">.</span><span class="hl-6">debug</span><span class="hl-1">({</span><span class="hl-0">myProp:</span><span class="hl-1"> </span><span class="hl-3">'a string'</span><span class="hl-1">, </span><span class="hl-0">nested:</span><span class="hl-1"> {</span><span class="hl-0">anotherProps:</span><span class="hl-1"> [</span><span class="hl-3">'val1'</span><span class="hl-1">, </span><span class="hl-3">'val2'</span><span class="hl-1">], </span><span class="hl-0">boolProp:</span><span class="hl-1"> </span><span class="hl-4">true</span><span class="hl-1">}}, </span><span class="hl-3">'Test'</span><span class="hl-1">);</span><br/><span class="hl-1"> </span><span class="hl-7">/*</span><br/><span class="hl-7">[2024-03-07 11:39:37.687 -0500] DEBUG: Test</span><br/><span class="hl-7"> myProp: "a string"</span><br/><span class="hl-7"> nested: {</span><br/><span class="hl-7"> "anotherProps": [</span><br/><span class="hl-7"> "val1",</span><br/><span class="hl-7"> "val2"</span><br/><span class="hl-7"> ],</span><br/><span class="hl-7"> "boolProp": true</span><br/><span class="hl-7"> }</span><br/><span class="hl-7"> */</span>
8392</code><button type="button">Copy</button></pre>