Log Filtering: Package v.3.x

Overview

The third version of the library radically changes the log filtering mechanism presented in the second version for even greater flexibility and efficiency. Instead of implementing filters as classes that implement an interface IFilter, you can use a FluentAPI builder to create a filtering predicate that will be applied to the logs.

LogsFiltersConfiguration Class

Summary

LogsFiltersConfiguration is the central class of the package. It represents the configuration necessary for applying log filters according to specified rules.

Properties

• ApplyLogFilters: A bool property that gets or initializes a value indicating whether log filters should be applied. If set to true, the filtering rules defined in the QueryBuilder will be used for the logs.

• QueryBuilder: An optional property of type ILogQueryBuilder. It allows the definition of complex filtering rules through a fluent API. If not set, no filters will be applied.

ILogQueryBuilder Interface

Summary

ILogQueryBuilder serves as the foundation for building log filtering queries. It offers methods to define filters based on message content, exceptions, custom properties, and log levels.

Methods

• Message: Gets an IMessageRuleBuilder to define rules based on the log message.
• Exception: Gets an IExceptionRuleBuilder to define rules based on exceptions logged.
• Properties: Gets an IPropertiesRuleBuilder to define rules based on custom properties in the log entry.
• Level: Gets an ILevelRuleBuilder to define rules based on the log level.
• And(): Returns an ILogQueryBuilder for combining conditions with a logical AND.
• Or(): Returns an ILogQueryBuilder for combining conditions with a logical OR.

Rule Builders

IMessageRuleBuilder, IExceptionRuleBuilder, IPropertiesRuleBuilder, ILevelRuleBuilder

These interfaces inherit from ILogQueryBuilder and provide specific methods for defining rules based on different aspects of log entries:

• Contains: Adds a condition for entries that contain the specified substring.
• NotContains: Adds a condition for entries that do not contain the specified substring.
• Equals: Adds a condition for entries that exactly match the specified value. For IMessageRuleBuilder and IExceptionRuleBuilder, the comparison is against the message content. For IPropertiesRuleBuilder, it matches against a key-value pair in the log entry's properties.
• NotEquals: Adds a condition for entries that do not match the specified value.
• Null: Adds a condition for entries where the specified field is null.
• NotNull: Adds a condition for entries where the specified field is not null.
• InRange (ILevelRuleBuilder only): This function adds a condition for entries within a specified log level range.
• NotInRange (ILevelRuleBuilder only): Adds a condition for entries outside a specified log level range.

Usage Example

var config = new LogsFiltersConfiguration
{
    ApplyLogFilters = true,
    QueryBuilder = new LogQueryBuilder()
        .Message.Contains("error")
        .And()
        .Properties.NotEquals("user", "admin", StringComparison.OrdinalIgnoreCase)
        .Or()
        .Level.InRange(LogEventLevel.Warning, LogEventLevel.Fatal)
};

In this example, the LogsFiltersConfiguration is set up to apply filters that include log entries containing the substring "error" in their message, but not from a user named "admin", or with a log level within the range from Warning to Fatal.

Troubleshooting:

To check the filter locally without running the complete logger, you can use the following code:

var filteringPredicate = LogQueryBuilder.Create()
    .Exception.NotContains("ExampleException") as IFilterExecutor;

var log = new LogEvent(
    timestamp: DateTimeOffset.Now,
    level: LogEventLevel.Fatal,
    exception: GetTestException(),
    messageTemplate: new MessageTemplate([]),
    properties: []
);

Console.WriteLine("Exception pass the filter: {0}", filteringPredicate!.Evaluate(log));
return;

Exception GetTestException()
    => new("ExampleException!: " +
           "This is a test exception to evaluate filter behavior");