Serilog.Expressions 4.0.0

The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org. Prefix Reserved
There is a newer prerelease version of this package available.
See the version list below for details.
dotnet add package Serilog.Expressions --version 4.0.0
NuGet\Install-Package Serilog.Expressions -Version 4.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Serilog.Expressions" Version="4.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Expressions --version 4.0.0
#r "nuget: Serilog.Expressions, 4.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Serilog.Expressions as a Cake Addin
#addin nuget:?package=Serilog.Expressions&version=4.0.0

// Install Serilog.Expressions as a Cake Tool
#tool nuget:?package=Serilog.Expressions&version=4.0.0

Serilog Expressions Build status NuGet Package

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

Getting started

Install the package from NuGet:

dotnet add package Serilog.Expressions

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.

Filtering example

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.

An appSettings.json JSON configuration example

In appSettings.json configuration this is written as:

{
  "Serilog": {
    "Using": ["Serilog.Expressions"],
    "Filter": [
      {
        "Name": "ByExcluding",
        "Args": {
          "expression": "RequestPath like '/health%'"
        }
      }
    ]
  }
}
An <appSettings> XML configuration example

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>

Supported configuration APIs

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

Formatting with ExpressionTemplate

Serilog.Expressions includes the ExpressionTemplate class for text formatting. ExpressionTemplate implements ITextFormatter, so it works with any text-based Serilog sink, including Console, File, Debug, and Email:

// using Serilog.Templates;

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

// Produces log events like:
// [21:21:40 INF (Sample.Program)] Cart contains ["Tea","Coffee"] (first item is Tea)

Templates are based on .NET format strings, and support standard padding, alignment, and format specifiers.

Along with standard properties for the event timestamp (@t), level (@l) and so on, "holes" in expression templates can include complex expressions over the first-class properties of the event, like {SourceContext} and {Cart[0]} in the example..

Templates support customizable color themes when used with the Console sink:

    .WriteTo.Console(new ExpressionTemplate(
        "[{@t:HH:mm:ss} {@l:u3}] {@m}\n{@x}", theme: TemplateTheme.Code))

Screenshot showing colored terminal output

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

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

Language reference

Properties

The following properties are available in expressions:

  • All first-class properties of the event - no special syntax: SourceContext and Cart are used in the formatting examples 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']
  • @i - event id; a 32-bit numeric hash of the event's message template
  • @r - renderings; if any tokens in the message template include .NET-specific formatting, an array of rendered values for each such token

The built-in properties mirror those available in the CLEF format.

Literals

Data type Description Examples
Null Corresponds to .NET's null value null
Number A number in decimal or hexadecimal notation, represented by .NET decimal 0, 100, -12.34, 0xC0FFEE
String A single-quoted Unicode string literal; to escape ', double it 'pie', 'isn''t', '😋'
Boolean A Boolean value true, false
Array An array of values, in square brackets [1, 'two', null]
Object A mapping of string keys to values; keys that are valid identifiers do not need to be quoted {a: 1, 'b c': 2, d}

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

Operators and conditionals

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
  • Accessors a.b
  • Indexers a['b'] and a[0]
  • Wildcard indexing - a[?] any, and a[*] all
  • Conditional if a then b else c (all branches required; see also the section below on conditional blocks)

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

User.Name like 'n%' ci

Functions

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.
Function Description
Coalesce(p0, p1, [..pN]) Returns the first defined, non-null argument.
Concat(s0, s1, [..sN]) Concatenate two or more strings.
Contains(s, t) Tests whether the string s contains the substring t.
ElementAt(x, i) Retrieves a property of x by name i, or array element of x by numeric index i.
EndsWith(s, t) Tests whether the string s ends with substring t.
IndexOf(s, t) Returns the first index of substring t in string s, or -1 if the substring does not appear.
IndexOfMatch(s, p) Returns the index of the first match of regular expression p in string s, or -1 if the regular expression does not match.
IsMatch(s, p) Tests whether the regular expression p matches within the string s.
IsDefined(x) Returns true if the expression x has a value, including null, or false if x is undefined.
LastIndexOf(s, t) Returns the last index of substring t in string s, or -1 if the substring does not appear.
Length(x) Returns the length of a string or array.
Now() Returns DateTimeOffset.Now.
Rest([deep]) In an ExpressionTemplate, returns an object containing the first-class event properties not otherwise referenced in the template. If deep is true, also excludes properties referenced in the event's message template.
Round(n, m) Round the number n to m decimal places.
StartsWith(s, t) Tests whether the string s starts with substring t.
Substring(s, start, [length]) Return the substring of string s from start to the end of the string, or of length characters, if this argument is supplied.
TagOf(o) Returns the TypeTag field of a captured object (i.e. where TypeOf(x) is 'object').
ToString(x, [format]) Convert x to a string, applying the format string format if x is IFormattable.
TypeOf(x) Returns a string describing the type of expression x: a .NET type name if x is scalar and non-null, or, 'array', 'object', 'dictionary', 'null', or 'undefined'.
Undefined() Explicitly mark an undefined value.
UtcDateTime(x) Convert a DateTime or DateTimeOffset into a UTC DateTime.

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

StartsWith(User.Name, 'n') ci

Template directives

Conditional blocks

Within an ExpressionTemplate, a portion of the template can be conditionally evaluated using #if.

Log.Logger = new LoggerConfiguration()
    .WriteTo.Console(new ExpressionTemplate(
        "[{@t:HH:mm:ss} {@l:u3}{#if SourceContext is not null} ({SourceContext}){#end}] {@m}\n{@x}"))
    .CreateLogger();

// Produces log events like:
// [21:21:45 INF] Starting up
// [21:21:46 INF (Sample.Program)] Firing engines

The block between the {#if <expr>} and {#end} directives will only appear in the output if <expr> is true - in the example, events with a SourceContext include this in parentheses, while those without, don't.

It's important to notice that the directive requires a Boolean true before the conditional block will be evaluated. It wouldn't be sufficient in this case to write {#if SourceContext}, since no values other than true are considered "truthy".

The syntax supports {#if <expr>}, chained {#else if <expr>}, {#else}, and {#end}, with arbitrary nesting.

Repetition

If a log event includes structured data in arrays or objects, a template block can be repeated for each element or member using #each/in (newlines, double quotes and construction of the ExpressionTemplate omitted for clarity):

{@l:w4}: {SourceContext}
      {#each s in Scope}=> {s}{#delimit} {#end}
      {@m}
{@x}

This example uses the optional #delimit to add a space between each element, producing output like:

info: Sample.Program
      => Main => TextFormattingExample
      Hello, world!

When using {#each <name> in <expr>} over an object, such as the built-in @p (properties) object, <name> will be bound to the names of the properties of the object.

To get to the values of the properties, use a second binding:

{#each k, v in @p}{k} = {v}{#delimit},{#end}

This example, if an event has three properties, will produce output like:

Account = "nblumhardt", Cart = ["Tea", "Coffee"], Powerup = 42

The syntax supports {#each <name>[, <name>] in <expr>}, an optional {#delimit} block, and finally an optional {#else} block, which will be evaluated if the array or object is empty.

Recipes

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.

Write not-referenced context properties (only if there are any):

{#if rest(true) <> {}} <Context: {rest(true)}>{#end}

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).

Working with the raw API

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.");
    }

Implementing user-defined functions

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

  • Return LogEventPropertyValue?,
  • Have arguments of type LogEventPropertyValue? or LogEvent,
  • If the ci modifier is supported, accept a StringComparison, and
  • If culture-specific formatting or comparisons are used, accepts an IFormatProvider.

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)", nameResolver: myFunctions);
// Filter events based on whether `User.Name` is `'Hello'` :-)

Acknowledgements

Includes the parser combinator implementation from Superpower, copyright Datalust, Superpower Contributors, and Sprache Contributors; licensed under the Apache License, 2.0.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (83)

Showing the top 5 NuGet packages that depend on Serilog.Expressions:

Package Downloads
Umbraco.Cms.Infrastructure The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Contains the infrastructure assembly needed to run Umbraco CMS.

Blauhaus.Analytics.Serilog

Package Description

SyncSoft.App.Serilog

An app framework for SyncSoft Inc.

ComplianceAuditSystems.AcabimCommonServices

Package Description

Flour.Logging

Flour.Logging

GitHub repositories (27)

Showing the top 5 popular GitHub repositories that depend on Serilog.Expressions:

Repository Stars
EventStore/EventStore
EventStoreDB, the event-native database. Designed for Event Sourcing, Event-Driven, and Microservices architectures
anjoy8/Blog.Core
💖 ASP.NET Core 8.0 全家桶教程,前后端分离后端接口,vue教程姊妹篇,官方文档:
umbraco/Umbraco-CMS
The simple, flexible and friendly ASP.NET CMS used by more than 730.000 websites
fullstackhero/dotnet-webapi-starter-kit
production grade .net 8 webapi starter kit with multitenancy support and clean code. 🔥
BililiveRecorder/BililiveRecorder
录播姬 | mikufans 生放送录制
Version Downloads Last updated
4.0.1-dev-00154 454 3/5/2024
4.0.1-dev-00151 10,892 1/7/2024
4.0.0 2,232,254 11/9/2023
4.0.0-dev-00143 93 11/9/2023
4.0.0-dev-00139 7,693 10/3/2023
4.0.0-dev-00137 41,755 9/18/2023
3.4.2-dev-00131 290 9/18/2023
3.4.2-dev-00130 87 9/18/2023
3.4.2-dev-00120 20,950 5/22/2023
3.4.2-dev-00119 73,003 11/11/2022
3.4.1 14,611,658 10/10/2022
3.4.1-dev-00111 147 10/10/2022
3.4.1-dev-00109 489 9/30/2022
3.4.1-dev-00107 186 9/29/2022
3.4.1-dev-00102 281 9/27/2022
3.4.1-dev-00095 528 9/14/2022
3.4.0 7,473,171 5/12/2022
3.4.0-dev-00089 185 5/11/2022
3.3.0 5,146,051 2/22/2022
3.3.0-dev-00088 167 5/11/2022
3.3.0-dev-00086 170 5/10/2022
3.2.2-dev-00083 4,906 2/14/2022
3.2.2-dev-00078 893 2/8/2022
3.2.1 2,653,168 11/3/2021
3.2.1-dev-00074 7,848 11/3/2021
3.2.1-dev-00071 18,601 8/4/2021
3.2.1-dev-00070 524 6/23/2021
3.2.1-dev-00069 620 6/21/2021
3.2.0 2,922,956 6/21/2021
3.2.0-dev-00064 259 6/21/2021
3.1.1-dev-00063 236 6/21/2021
3.1.1-dev-00061 217 6/20/2021
3.1.1-dev-00059 248 6/20/2021
3.1.1-dev-00058 258 6/20/2021
3.1.1-dev-00054 250 6/15/2021
3.1.1-dev-00051 257 6/9/2021
3.1.0 484,795 6/4/2021
3.1.0-dev-00048 230 6/4/2021
3.0.0 31,515 6/2/2021
3.0.0-dev-00043 302 6/1/2021
3.0.0-dev-00041 260 5/31/2021
3.0.0-dev-00039 535 5/25/2021
2.0.0 3,647,500 3/27/2021
2.0.0-dev-00032 246 3/22/2021
2.0.0-dev-00030 327 3/21/2021
1.1.1 478,738 3/8/2021
1.1.1-dev-00024 231 3/8/2021
1.1.0 2,669 3/7/2021
1.1.0-dev-00022 268 3/7/2021
1.1.0-dev-00021 273 3/3/2021
1.1.0-dev-00020 6,642 12/22/2020
1.0.0 1,385,704 11/6/2020
1.0.0-main-00017 325 11/6/2020
1.0.0-dev-00015 1,439 10/7/2020
1.0.0-dev-00014 328 10/1/2020
1.0.0-dev-00013 347 10/1/2020
1.0.0-dev-00012 383 10/1/2020
1.0.0-dev-00011 323 9/23/2020
1.0.0-dev-00010 354 9/23/2020
1.0.0-dev-00009 307 9/23/2020
1.0.0-dev-00008 326 9/22/2020
1.0.0-dev-00007 314 9/21/2020
1.0.0-dev-00006 349 9/21/2020
1.0.0-dev-00005 350 9/21/2020
1.0.0-dev-00004 341 9/16/2020
1.0.0-dev-00003 340 9/16/2020