Filter Plugin Browser Server

Plugin Source

A plugin that filters log messages. You can filter logs using string patterns, regular expressions, or JSON Queries.

Installation

npm

npm install @loglayer/plugin-filter

pnpm

pnpm add @loglayer/plugin-filter

yarn

yarn add @loglayer/plugin-filter

Usage

import { filterPlugin } from '@loglayer/plugin-filter';

// Create a filter that only allows error messages
const filter = filterPlugin({
  // checks the assembled message using an includes()
  messages: ['error'],
});

// Checks the level of the log
const levelFilter = filterPlugin({
  queries: ['.level == "error" or .level == "warn"'],
});

Configuration Options

Optional Parameters

Name	Type	Default	Description
messages	Array<string | RegExp>	-	Array of string patterns or regular expressions to match against log messages
queries	string[]	-	Array of JSON queries to filter logs. A JSON Query filter() is applied, with each item being part of an OR condition
debug	boolean	false	Enable debug mode for troubleshooting
disabled	boolean	false	Disable the plugin

Message Pattern Matching

You can filter logs using string patterns or regular expressions:

// Using string patterns
const filter = filterPlugin({
  messages: ['error', 'warning'],
});

// Using regular expressions
const regexFilter = filterPlugin({
  messages: [/error/i, /warning\d+/],
});

// Mixed patterns
const mixedFilter = filterPlugin({
  messages: ['error', /warning\d+/],
});

Query-Based Filtering

You can use JSON Queries to filter logs based on any field.

Usage

const filter = filterPlugin({
  // each item is used as an OR condition
  queries: [
    // Filter by log level
    '.level == "error"',
    // Filter by data properties
    '.data.userId == 123',
    // Complex conditions
    '(.level == "error") and (.data.retryCount > 3)',
  ],
});

TIP

For joining conditions, wrap them in parentheses.

This would translate in JSON Query to:

filter((.level == "error") or (.data.userId == 123) or ((.level == "error") and (.data.retryCount > 3)))

INFO

• filter() is added around the queries by the plugin.
• Single-quotes are converted to double-quotes.

Query Context

The queries are executed against an array containing an object that is defined as the following:

[{
  level: string;    // Log level
  message: string;  // Combined log message
  data: object;     // Additional log data, which includes, error data, context data and metadata
}]

If you did the following:

log.withMetadata({ userId: '123' }).error('Failed to process request');

Then the query context would be:

{
  level: 'error',
  message: 'Failed to process request',
  data: { userId: '123' }
}

Example Queries

// Filter by log level
[".level == 'error'"]

// Filter by message content
// see: https://github.com/jsonquerylang/jsonquery/blob/main/reference/functions.md#regex
["regex(.message, 'test', 'i')"]

// Filter by data properties
[".data.user.age == 25"]

// Complex conditions
["(.level == "error") and (.data.retryCount > 3)"]

Debug Mode

Enable debug mode to see detailed information about the filtering process:

const filter = filterPlugin({
  messages: ['error'],
  queries: ['.level == "error"'],
  debug: true,
});

Filter Logic

The plugin follows this logic when filtering logs:

1. If no filters are defined (no messages and no queries), allow all logs
2. If message patterns are defined, check them first
   • If any pattern matches, allow the log
3. If no message patterns match (or none defined) and queries are defined:
   • Execute queries
   • If any query matches, allow the log
4. If no patterns or queries match, filter out the log

Changelog

View the changelog here.