Repository files navigation

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

A simpleHello, {User} event.

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

Install fromNuGet:

dotnet add package Serilog.Formatting.Compact

The formatter is used in conjunction with sinks that acceptITextFormatter. For example, thefile sink:

Log.Logger=newLoggerConfiguration().WriteTo.File(newCompactJsonFormatter(),"./logs/myapp.json").CreateLogger();

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

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

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

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

CompactJsonFormatter will preserve the message template, properties, and formatting information so that the rendered message can be created at a later point. When theJSON 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 asanevent idgenerated from the message template, into the event:

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

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

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.

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

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

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 typeapplication/vnd.serilog.clef.

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

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

Event

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

DefaultJsonFormatter 292 bytes

{"Timestamp":"2016-06-07T13:44:57.8532799+10:00","Level":"Information","MessageTemplate":"Hello, {@User}, {N:x8} at {Now}","Properties":{"User":{"Name":"nblumhardt","Tags":[1,2,3]},"N":123,"Now":"2016-06-07T13:44:57.8532799+10:00"},"Renderings":{"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

Seetest/Serilog.Formatting.Compact.Tests/FormattingBenchmarks.cs.

Several tools are available for working with the CLEF format.

• Analogy.LogViewer.Serilog - CLEF parser forAnalogy Log Viewer
• clef-tool - a CLI application for processing CLEF files
• Compact Log Format Viewer - a cross-platform viewer for CLEF files
• seqcli - pretty-print CLEF files at the command-line, oringest CLEF files intoSeq for search, and analysis
• Serilog.Formatting.Compact.Reader - convert CLEF documents back into SerilogLogEvents

Serilog.Formatting.Compact is not intended to provide customizable formatters. Seethis blog post for comprehensive Serilog JSON output customization examples.