Serilog.Formatting.Compact
3.0.0-dev-00980
Prefix Reserved
See the version list below for details.
dotnet add package Serilog.Formatting.Compact --version 3.0.0-dev-00980
NuGet\Install-Package Serilog.Formatting.Compact -Version 3.0.0-dev-00980
<PackageReference Include="Serilog.Formatting.Compact" Version="3.0.0-dev-00980" />
paket add Serilog.Formatting.Compact --version 3.0.0-dev-00980
#r "nuget: Serilog.Formatting.Compact, 3.0.0-dev-00980"
// Install Serilog.Formatting.Compact as a Cake Addin #addin nuget:?package=Serilog.Formatting.Compact&version=3.0.0-dev-00980&prerelease // Install Serilog.Formatting.Compact as a Cake Tool #tool nuget:?package=Serilog.Formatting.Compact&version=3.0.0-dev-00980&prerelease
Serilog.Formatting.Compact
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:
dotnet add 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 |
@tr |
Trace id | The id of the trace that was active when the event was created, if any | |
@sp |
Span id | The id of the span that was active when the event was created, if any |
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.
- Analogy.LogViewer.Serilog - CLEF parser for Analogy 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 into Seq for search, and analysis- Serilog.Formatting.Compact.Reader - convert CLEF documents back into Serilog
LogEvent
s
Customizing output
Serilog.Formatting.Compact is not intended to provide customizable formatters. See this blog post for comprehensive Serilog JSON output customization examples.
Product | Versions 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 was computed. 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 is compatible. 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 was computed. |
.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. |
NuGet packages (219)
Showing the top 5 NuGet packages that depend on Serilog.Formatting.Compact:
Package | Downloads |
---|---|
Serilog.AspNetCore
Serilog support for ASP.NET Core logging |
|
Serilog.Sinks.Elasticsearch
Serilog sink for Elasticsearch |
|
Serilog.Extensions.Logging.File
Add file logging to ASP.NET Core apps with one line of code. |
|
Umbraco.Cms.Infrastructure
Contains the infrastructure assembly needed to run Umbraco CMS. |
|
UmbracoCms.Core
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 (50)
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
Umbraco is a free and open source .NET content management system helping you deliver delightful digital experiences.
|
|
BililiveRecorder/BililiveRecorder
录播姬 | mikufans 生放送录制
|
|
fullstackhero/blazor-starter-kit
Clean Architecture Template for Blazor WebAssembly Built with MudBlazor Components.
|
|
nuke-build/nuke
🏗 The AKEless Build System for C#/.NET
|
Version | Downloads | Last updated |
---|---|---|
3.0.0 | 4,979,200 | 6/9/2024 |
3.0.0-dev-00980 | 191 | 6/9/2024 |
2.0.1-dev-00969 | 19,481 | 2/5/2024 |
2.0.0 | 58,353,260 | 11/9/2023 |
2.0.0-dev-00962 | 729 | 11/9/2023 |
2.0.0-dev-00961 | 88,675 | 10/4/2023 |
1.1.1-dev-00944 | 540,487 | 5/11/2021 |
1.1.1-dev-00940 | 135,241 | 3/6/2020 |
1.1.1-dev-00939 | 7,097 | 3/6/2020 |
1.1.0 | 305,508,614 | 10/17/2019 |
1.1.0-dev-00934 | 1,561 | 10/17/2019 |
1.0.1-dev-00933 | 4,591 | 10/6/2019 |
1.0.1-dev-00929 | 1,690 | 10/5/2019 |
1.0.1-dev-00925 | 107,172 | 1/24/2019 |
1.0.1-dev-00922 | 367,935 | 10/23/2016 |
1.0.1-dev-00920 | 2,910 | 8/29/2016 |
1.0.0 | 134,314,655 | 7/5/2016 |
1.0.0-rc-916 | 2,104 | 6/26/2016 |
1.0.0-rc-915 | 1,992 | 6/26/2016 |
1.0.0-rc-912 | 2,084 | 6/25/2016 |
1.0.0-rc-9 | 2,073 | 6/22/2016 |
1.0.0-rc-6 | 2,018 | 6/21/2016 |
1.0.0-rc-5 | 2,030 | 6/21/2016 |
1.0.0-rc-3 | 1,951 | 6/21/2016 |
1.0.0-rc-10 | 1,967 | 6/22/2016 |