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 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.

Tools and resources

Various tools are available for working with the CLEF format.

Acknowledgements

CLEF was originally developed as part of the Serilog project.