Serilog.Formatting.Compact 2.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.Formatting.Compact --version 2.0.0
NuGet\Install-Package Serilog.Formatting.Compact -Version 2.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.Formatting.Compact" Version="2.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Serilog.Formatting.Compact --version 2.0.0
#r "nuget: Serilog.Formatting.Compact, 2.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.Formatting.Compact as a Cake Addin
#addin nuget:?package=Serilog.Formatting.Compact&version=2.0.0

// Install Serilog.Formatting.Compact as a Cake Tool
#tool nuget:?package=Serilog.Formatting.Compact&version=2.0.0

Serilog.Formatting.Compact Build status NuGet

A simple, compact JSON-based event format for Serilog. CompactJsonFormatter significantly reduces the byte count of small log events when compared with Serilog's default JsonFormatter, while remaining human-readable. It achieves this through shorter built-in property names, a leaner format, and by excluding redundant information.

Sample

A simple Hello, {User} event.

{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {User}","User":"nblumhardt"}

Getting started

Install from NuGet:

Install-Package Serilog.Formatting.Compact

The formatter is used in conjunction with sinks that accept ITextFormatter. For example, the file sink:

Log.Logger = new LoggerConfiguration()
  .WriteTo.File(new CompactJsonFormatter(), "./logs/myapp.json")
  .CreateLogger();
XML <appSettings> configuration

To specify the formatter in XML <appSettings> provide its assembly-qualified type name:

<appSettings>
  <add key="serilog:using:File" value="Serilog.Sinks.File" />
  <add key="serilog:write-to:File.path" value="./logs/myapp.json" />
  <add key="serilog:write-to:File.formatter"
       value="Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact" />
JSON appsettings.json configuration

To specify formatter in json appsettings.json provide its assembly-qualified type name:

{
  "Serilog": {
    "WriteTo": [
      {
        "Name": "File",
        "Args": {
          "path": "./logs/myapp.json",
          "formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"
        }
      }
    ]
  }
}

Rendered events

CompactJsonFormatter will preserve the message template, properties, and formatting information so that the rendered message can be created at a later point. When the JSON is intended for consumption in an environment without message template rendering, RenderedCompactJsonFormatter can be used instead.

Instead of the message template, RenderedCompactJsonFormatter writes the fully-rendered message, as well as an event id generated from the message template, into the event:

{"@t":"2016-06-07T03:44:57.8532799Z","@m":"Hello, \"nblumhardt\"","@i":"7a8b9c0d","User":"nblumhardt"}

Format details

The format written by the compact formatters is specified generically so that implementations for other logging libraries, including Microsoft.Extensions.Logging, are possible if desired.

Payload

Each event is a JSON object with event data at the top level. Any JSON property on the payload object is assumed to be a regular property of the event, apart from the reified properties below.

Reified properties

The format defines a handful of reified properties that have special meaning:

Property Name Description Required?
@t Timestamp An ISO 8601 timestamp Yes
@m Message A fully-rendered message describing the event
@mt Message Template Alternative to Message; specifies a message template over the event's properties that provides for rendering into a textual description of the event
@l Level An implementation-specific level identifier (string or number) Absence implies "informational"
@x Exception A language-dependent error representation potentially including backtrace
@i Event id An implementation specific event id (string or number)
@r Renderings If @mt includes tokens with programming-language-specific formatting, an array of pre-rendered values for each such token May be omitted; if present, the count of renderings must match the count of formatted tokens exactly

The @ sigil may be escaped at the start of a user property name by doubling, e.g. @@name denotes a property called @name.

Batch format

When events are batched into a single payload, a newline-delimited stream of JSON documents is required. Either \n or \r\n delimiters may be used. Batches of newline-separated compact JSON events can use the (unofficial) MIME type application/vnd.serilog.clef.

Versioning

Versioning would be additive only, with no version identifier; implementations should treat any unrecognised reified properties as if they are user data.

Comparison

The output and benchmarks below compare the compact JSON formatter with Serilog's built-in JsonFormatter.

Event

Log.Information("Hello, {@User}, {N:x8} at {Now}",
  new
  {
    Name = "nblumhardt",
    Tags = new[] { 1, 2, 3 }
  },
  123,
  DateTime.Now);

Default JsonFormatter 292 bytes

{"Timestamp":"2016-06-07T13:44:57.8532799+10:00","Level":"Information","MessageT
emplate":"Hello, {@User}, {N:x8} at {Now}","Properties":{"User":{"Name":"nblumha
rdt","Tags":[1,2,3]},"N":123,"Now":"2016-06-07T13:44:57.8532799+10:00"},"Renderi
ngs":{"N":[{"Format":"x8","Rendering":"0000007b"}]}}

CompactJsonFormatter 187 bytes (0.64)

{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {@User}, {N:x8} at {Now}","@r
":["0000007b"],"User":{"Name":"nblumhardt","Tags":[1,2,3]},"N":123,"Now":2016-06
-07T13:44:57.8532799+10:00}

Formatting benchmark

See test/Serilog.Formatting.Compact.Tests/FormattingBenchmarks.cs.

Formatter Median StdDev Scaled
JsonFormatter 11.2775 µs 0.0682 µs 1.00
CompactJsonFormatter 6.0315 µs 0.0429 µs 0.53
JsonFormatter(renderMessage: true) 13.7585 µs 0.1194 µs 1.22
RenderedCompactJsonFormatter 7.0680 µs 0.0605 µs 0.63

Tools

Several tools are available for working with the CLEF format.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  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 is compatible.  net463 was computed.  net47 was computed.  net471 is compatible.  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 (187)

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

Package Downloads
Serilog.AspNetCore The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Serilog support for ASP.NET Core logging

Serilog.Sinks.Elasticsearch

Serilog sink for Elasticsearch

Serilog.Extensions.Logging.File The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Add file logging to ASP.NET Core apps with one line of code.

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.

UmbracoCms.Core The ID prefix of this package has been reserved for one of the owners of this package by NuGet.org.

Contains the core assemblies needed to run Umbraco Cms. This package only contains assemblies and can be used for package development. Use the UmbracoCms package to setup Umbraco in Visual Studio as an ASP.NET project.

GitHub repositories (51)

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

Repository Stars
microsoft/reverse-proxy
A toolkit for developing high-performance HTTP reverse proxy applications.
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 生放送录制
fullstackhero/blazor-starter-kit
Clean Architecture Template for Blazor WebAssembly Built with MudBlazor Components.
Version Downloads Last updated
2.0.1-dev-00969 4,376 2/5/2024
2.0.0 11,284,441 11/9/2023
2.0.0-dev-00962 626 11/9/2023
2.0.0-dev-00961 65,032 10/4/2023
1.1.1-dev-00944 427,145 5/11/2021
1.1.1-dev-00940 125,002 3/6/2020
1.1.1-dev-00939 6,585 3/6/2020
1.1.0 252,915,431 10/17/2019
1.1.0-dev-00934 1,476 10/17/2019
1.0.1-dev-00933 4,052 10/6/2019
1.0.1-dev-00929 1,598 10/5/2019
1.0.1-dev-00925 105,396 1/24/2019
1.0.1-dev-00922 364,245 10/23/2016
1.0.1-dev-00920 2,801 8/29/2016
1.0.0 122,879,660 7/5/2016
1.0.0-rc-916 2,030 6/26/2016
1.0.0-rc-915 1,906 6/26/2016
1.0.0-rc-912 1,993 6/25/2016
1.0.0-rc-9 1,985 6/22/2016
1.0.0-rc-6 1,933 6/21/2016
1.0.0-rc-5 1,938 6/21/2016
1.0.0-rc-3 1,876 6/21/2016
1.0.0-rc-10 1,878 6/22/2016