A simple, modern, JSON-based format for structured application logs. CLEF places minimal requirements on the schema of application log events, but specifies enough to enable useful interoperability between tools.
Each event is a single JSON object. 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:
| 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 or severity 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, identifying the type of the event (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.
A simple Hello, {User} event that occured on June 7th, 2016:
{"@t":"2016-06-07T03:44:57.8532799Z","@mt":"Hello, {User}","User":"nblumhardt"}
When multiple events are written to a text file or stream:
\n, \r\n, or the end of the file/stream.Encoding is not specified, but in the absence of a clearly designated encoding, UTF-8 should be assumed.
Versioning of the CLEF format is additive only, with no version identifier; implementations should treat any unrecognised reified properties as if they are user data.
For example, if an implementation encounters a top-level document property @y, which is unknown to the standard, this should be regarded as a regular property of the event with the name @y, and not (for example) stripped of its prefix and given the bare name y.
By convention, CLEF documents use the unregistered application/vnd.serilog.clef MIME type.
Various tools are available for working with the CLEF format.
clef-tool - a CLI application for processing CLEF filesseqcli - pretty-print CLEF files at the command-lineLogEventsCLEF was originally developed as part of the Serilog project.