Advanced Usage

Zario's advanced features — Filters, Enrichers, and Aggregators — provide powerful mechanisms for fine-grained control over log emission, data enrichment, and optimized log processing. This guide will walk you through leveraging these capabilities to build a highly customizable and efficient logging solution.

Filters

Filters allow you to selectively control which log messages are emitted by your logger. They act as gatekeepers, evaluating LogData against specified criteria before it's sent to any [transports] or [aggregators]. This helps reduce log noise and ensures that only relevant information is processed.

All filters implement the Filter interface:

The shouldEmit method returns true if the log should be processed further, and false if it should be discarded.

Integrating Filters with Your Logger

You can provide an array of filters when initializing your Logger instance:

You can also add or remove filters dynamically at runtime using addFilter() and removeFilter():

Types of Filters

Zario provides several built-in filter types, each designed for specific use cases:

PredicateFilter

Filters logs based on a custom function you provide.

LevelFilter

Filters logs based on a predefined list of allowed log [levels].

PrefixFilter

Filters logs based on their prefix property.

MetadataFilter

Filters logs by checking if their metadata contains specific key-value pairs. All specified key-value pairs must match for the log to be emitted.

FieldFilter

Filters logs based on a single specific field within the metadata and its expected value.

CompositeFilter

Combines multiple filters using an "AND" logic. All contained filters must return true for the log to be emitted.

OrFilter

Combines multiple filters using an "OR" logic. If any of the contained filters return true, the log is emitted.

NotFilter

Negates the result of another filter. If the wrapped filter returns true, NotFilter returns false, and vice-versa.

Enrichers (Structured Logging)

Enrichers are functions that modify or add data to a log record's LogData before it is formatted and sent to transports or aggregators. This is especially useful for [structured logging], allowing you to inject consistent contextual information into every log, making them more searchable and analyzable.

An LogEnricher is simply a function that takes LogData and returns modified LogData:

Integrating Enrichers with Your Logger

Enrichers are managed through a LogEnrichmentPipeline. You can provide an instance of this pipeline when initializing your Logger:

You can also add enrichers dynamically at runtime using addEnricher():

MetadataEnricher

The MetadataEnricher class provides static helper methods to easily create common enricher functions for adding metadata:

MetadataEnricher.addStaticFields(staticFields: { [key: string]: any })

Adds fixed key-value pairs to the metadata of every log.

MetadataEnricher.addDynamicFields(dynamicFields: () => { [key: string]: any })

Adds dynamically computed key-value pairs to the metadata of every log. The provided function is called for each log message.

Note: MetadataEnricher.addContext is an alias for MetadataEnricher.addStaticFields.

MetadataEnricher.addProcessInfo()

Automatically adds current process information (PID, hostname, Node.js version) to log metadata.

MetadataEnricher.addEnvironmentInfo()

Automatically adds environment information (NODE_ENV, platform, architecture) to log metadata.

LogEnrichmentPipeline

This class manages a sequence of LogEnricher functions. When process() is called, each enricher is applied in the order they were added, modifying the LogData as it passes through the pipeline.

Custom Enrichers

You can define your own custom LogEnricher functions to implement highly specific enrichment logic.

Aggregators

Aggregators are components that collect log messages over time or by quantity before performing an action, such as sending them to a remote service or writing them to a file in batches. This approach can significantly improve performance by reducing the frequency of I/O operations or network requests.

All aggregators implement the LogAggregator interface:

• aggregate: Receives a log message to add to the internal buffer.
• flush: Forces the aggregator to process its buffered logs.

Integrating Aggregators with Your Logger

You can provide an array of aggregators when initializing your Logger instance:

You can also add or remove aggregators dynamically:

Types of Aggregators

Zario provides three main types of aggregators:

BatchAggregator

Collects logs until a certain maxSize (number of logs) is reached, then flushes them using a provided callback.

TimeBasedAggregator

Collects logs over a specified flushInterval (in milliseconds), then flushes them.

CompositeAggregator

Allows you to combine multiple aggregators. A single log message sent to the CompositeAggregator will be passed to all its contained aggregators.