An embeddable mini-language for filtering, enriching, and formatting Serilog events, ideal for use with JSON or XML configuration.

Install the package from NuGet:

dotnet add package Serilog.Expressions -v 1.0.0-*

The package adds extension methods to Serilog's Filter, WriteTo, and Enrich configuration objects, along with an ExpressionTemplate type that's compatible with Serilog sinks accepting an ITextFormatter.

Serilog.Expressions adds ByExcluding() and ByIncludingOnly() overloads to the Filter configuration object that accept filter expressions:

Log.Logger = new LoggerConfiguration()
    .Filter.ByExcluding("RequestPath like '/health%'")
    .CreateLogger();

Events with a RequestPath property that matches the expression will be excluded by the filter.

Note that if the expression syntax is invalid, an ArgumentException will be thrown from the ByExcluding() method, and by similar methods elsewhere in the package. To check expression syntax without throwing, see the Try*() methods in the SerilogExpression class.

In appSettings.json configuration this is written as:

{
  "Serilog": {
    "Using": ["Serilog.Expressions"],
    "Filter": [
      {
        "Name": "ByExcluding",
        "Args": {
          "expression": "RequestPath like '/health%'"
        }
      }
    ]
  }
}

In XML configuration files, this is written as:

  <appSettings>
    <add key="serilog:using:Expressions" value="Serilog.Expressions" />
    <add key="serilog:filter:ByExcluding.expression" value="RequestPath like '/health%'" />
  </appSettings>

Serilog.Expressions adds a number of expression-based overloads and helper methods to the Serilog configuration syntax:

• Filter.ByExcluding(), Filter.ByIncludingOnly() - use an expression to filter events passing through the Serilog pipeline
• WriteTo.Conditional() - use an expression to select the events passed to a particular sink
• Enrich.When() - conditionally enable an enricher when events match an expression
• Enrich.WithComputed() - add or modify event properties using an expression

Serilog.Expressions includes the ExpressionTemplate class for text formatting. ExpressionTemplate implements ITextFormatter, so it works with any text-based Serilog sink:

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(new ExpressionTemplate(
        "[{@t:HH:mm:ss} {@l:u3} ({SourceContext})] {@m} (first item is {Items[0]})\n{@x}"))
    .CreateLogger();

Note the use of {Items[0]}: "holes" in expression templates can include any valid expression.

Newline-delimited JSON (for example, emulating the CLEF format) can be generated using object literals:

    .WriteTo.Console(new ExpressionTemplate(
        "{ {@t, @mt, @l: if @l = 'Information' then undefined() else @l, @x, ..@p} }\n"))

The following properties are available in expressions:

• All first-class properties of the event; no special syntax: SourceContext and Items are used in the formatting example above
• @t - the event's timestamp, as a DateTimeOffset
• @m - the rendered message
• @mt - the raw message template
• @l - the event's level, as a LogEventLevel
• @x - the exception associated with the event, if any, as an Exception
• @p - a dictionary containing all first-class properties; this supports properties with non-identifier names, for example @p['snake-case-name']

Array and object literals support the spread operator: [1, 2, ..rest], {a: 1, ..other}. Specifying an undefined property in an object literal will remove it from the result: {..User, Email: Undefined()}

A typical set of operators is supported:

• Equality = and inequality <>, including for arrays and objects
• Boolean and, or, not
• Arithmetic +, -, *, /, ^, %
• Numeric comparison <, <=, >, >=
• Existence is null and is not null
• SQL-style like and not like, with % and _ wildcards (double wildcards to escape them)
• Array membership with in and not in
• Indexers a[b] and accessors a.b
• Wildcard indexing - a[?] any, and a[*] all
• Conditional if a then b else c (all branches required)

Comparision operators that act on text all accept an optional postfix ci modifier to select case-insensitive comparisons:

User.Name like 'n%' ci

Functions are called using typical Identifier(args) syntax.

Except for the IsDefined() function, the result of calling a function will be undefined if:

• any argument is undefined, or
• any argument is of an incompatible type.

Functions that compare text accept an optional postfix ci modifier to select case-insensitive comparisons:

StartsWith(User.Name, 'n') ci

Trim down SourceContext to a type name only:

Substring(SourceContext, LastIndexOf(SourceContext, '.') + 1)

This expression takes advantage of LastIndexOf() returning -1 when no . character appears in SourceContext, to yield a startIndex of 0 in that case.

Access a property with a non-identifier name:

@p['some name']

Any structured value, including the built-in @p, can be indexed by string key. This means that User.Name and User['Name'] are equivalent, for example.

Access a property with inconsistent casing:

ElementAt(@p, 'someName') ci

ElementAt() is a function-call version of the [] indexer notation, which means it can accept the ci case-insensitivity modifier.

Format events as newline-delimited JSON (template, embedded in C# or JSON):

{ {Timestamp: @t, Username: User.Name} }\n

This output template shows the use of a space between the opening { of a hole, and the enclosed object literal with Timestamp and Username fields. The object will be formatted as JSON. The trailing \n is a C# or JSON newline literal (don't escape this any further, as it's not part of the output template syntax).

The package provides the class SerilogExpression in the Serilog.Expressions namespace for working with expressions.

if (SerilogExpression.TryCompile("RequestPath like '/health%'", out var compiled, out var error)
{
    // `compiled` is a function that can be executed against `LogEvent`s:
    var result = compiled(someEvent);

    // `result` will contain a `LogEventPropertyValue`, or `null` if the result of evaluating the
    // expression is undefined (for example if the event has no `RequestPath` property).
    if (result is ScalarValue value &&
        value.Value is bool matches &&
        matches)
    {
        Console.WriteLine("The event matched.");
    }
}
else
{
    // `error` describes a syntax error.
    Console.WriteLine($"Couldn't compile the expression; {error}.");
}

Compiled expression delegates return LogEventPropertyValue because this is the most convenient type to work with in many Serilog scenarios (enrichers, sinks, ...). To convert the result to plain-old-.NET-types like string, bool, Dictionary<K,V> and Array, use the functions in the Serilog.Expressions.ExpressionResult class:

    var result = compiled(someEvent);

    // `true` only if `result` is a scalar Boolean `true`; `false` otherwise:
    if (ExpressionResult.IsTrue(result))
    {
        Console.WriteLine("The event matched.");
    }

User-defined functions can be plugged in by implementing static methods that:

• Return LogEventPropertyValue?,
• Have arguments of type LogEventPropertyValue?, and
• If the ci modifier is supported, accept a StringComparison in the first argument position.

For example:

public static class MyFunctions
{    
    public static LogEventPropertyValue? IsHello(
        StringComparison comparison,
        LogEventPropertyValue? maybeHello)
    {
        if (maybeHello is ScalarValue sv && sv.Value is string s)
            return new ScalarValue(s.Equals("Hello", comparison));

        // Undefined - argument was not a string.
        return null;
    }
}

In the example, IsHello('Hello') will evaluate to true, IsHello('HELLO') will be false, IsHello('HELLO') ci will be true, and IsHello(42) will be undefined.

User-defined functions are supplied through an instance of NameResolver:

var myFunctions = new StaticMemberNameResolver(typeof(MyFunctions));
var expr = SerilogExpression.Compile("IsHello(User.Name)", new[] { myFunctions });
// Filter events based on whether `User.Name` is `'Hello'` :-)