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
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 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.
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():
Zario provides several built-in filter types, each designed for specific use cases:
PredicateFilterFilters logs based on a custom function you provide.
LevelFilterFilters logs based on a predefined list of allowed log [levels].
PrefixFilterFilters logs based on their prefix property.
MetadataFilterFilters logs by checking if their metadata contains specific key-value pairs. All specified key-value pairs must match for the log to be emitted.
FieldFilterFilters logs based on a single specific field within the metadata and its expected value.
CompositeFilterCombines multiple filters using an "AND" logic. All contained filters must return true for the log to be emitted.
OrFilterCombines multiple filters using an "OR" logic. If any of the contained filters return true, the log is emitted.
NotFilterNegates the result of another filter. If the wrapped filter returns true, NotFilter returns false, and vice-versa.
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:
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():
MetadataEnricherThe 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.
LogEnrichmentPipelineThis 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.
You can define your own custom LogEnricher functions to implement highly specific enrichment logic.
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.You can provide an array of aggregators when initializing your Logger instance:
You can also add or remove aggregators dynamically:
Zario provides three main types of aggregators:
BatchAggregatorCollects logs until a certain maxSize (number of logs) is reached, then flushes them using a provided callback.
TimeBasedAggregatorCollects logs over a specified flushInterval (in milliseconds), then flushes them.
CompositeAggregatorAllows you to combine multiple aggregators. A single log message sent to the CompositeAggregator will be passed to all its contained aggregators.