Compact Log Event Format (CLEF)

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.

Schema

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.

Example event

A simple Hello, {User} event that occured on June 7th, 2016:

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

Streams

When multiple events are written to a text file or stream:

Encoding

Encoding is not specified, but in the absence of a clearly designated encoding, UTF-8 should be assumed.

Versioning

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.

MIME type

By convention, CLEF documents use the unregistered application/vnd.serilog.clef MIME type.

Tools and resources

Various tools are available for working with the CLEF format.

Acknowledgements

CLEF was originally developed as part of the Serilog project.