What does Serilog.Formatting.Compact's CompactJsonFormatter write for each event, and when would you choose RenderedCompactJsonFormatter or the core JsonFormatter instead?
answer
- @t, @mt, @l, @x, @r
- @l omitted for Information
- @tr and @sp from Activity.Current
- one JSON object per line
- Rendered: @m plus @i event id
basics
~20 sCompactJsonFormatter writes one JSON object per line: @t, @mt, @r for formatted holes, @l (omitted for Information), @x, @tr/@sp, then every property at the top level. RenderedCompactJsonFormatter writes a rendered @m and an @i event id instead of @mt.
solid answer
~40 s`CompactJsonFormatter` from `Serilog.Formatting.Compact` is an `ITextFormatter` you pass to a sink, for example `WriteTo.File(new CompactJsonFormatter(), "logs/shipments.json")`. Each event is one newline-terminated JSON object with short reified fields: `@t` the UTC timestamp, `@mt` the message template, `@r` pre-rendered values for holes that have a format string, `@l` the level (left out when it is Information), `@x` the exception text, `@tr` and `@sp` the trace and span ids when an `Activity` was current, and then every property as a top-level field, destructured objects tagged with `$type`. `RenderedCompactJsonFormatter` replaces `@mt` with the rendered message `@m` and an event id `@i` hashed from the template, for consumers that cannot render templates. The core `JsonFormatter` is more verbose, with long names and a nested `Properties` object.
go deeper
Know that CompactJsonFormatter is passed to a sink such as WriteTo.File to get one JSON object per event.
Read a CLEF line: @t, @mt, @r, @l omitted for Information, @x, @tr and @sp, and top-level properties with $type on structures.
Choose between CompactJsonFormatter, RenderedCompactJsonFormatter and JsonFormatter based on what the log consumer can render and query.
Standardise one machine-readable log format across services so tooling, parsing and retention work the same everywhere.
## What a formatter is in Serilog Sinks that write text - console, file, and many network sinks - accept either an output template or an **`ITextFormatter`**. A formatter turns a `LogEvent` into text. For machine consumption you want JSON that keeps the template and every property intact, and **CLEF** (compact log event format), produced by `Serilog.Formatting.Compact`, is the common choice. ```csharp Log.Logger = new LoggerConfiguration() .Enrich.FromLogContext() .WriteTo.Console(new CompactJsonFormatter()) .WriteTo.File(new CompactJsonFormatter(), "logs/shipments.json", rollingInterval: RollingInterval.Day) .CreateLogger(); ``` In `appsettings.json` the formatter is given by assembly-qualified type name: `"formatter": "Serilog.Formatting.Compact.CompactJsonFormatter, Serilog.Formatting.Compact"`. ## The reified fields For `Log.Warning("Shipment {TrackingNumber} weighs {WeightKg:0.0} kg", "CX-1042", 31.27)` the formatter writes, in this order: | Field | Content | When present | |---|---|---| | `@t` | timestamp, converted to UTC, ISO 8601 round-trip format | always | | `@mt` | the message template text | always (compact) | | `@r` | array of renderings for holes with a format string - here `"31.3"` | only if some hole has a format | | `@l` | level name, such as `Warning` | omitted for Information | | `@x` | the exception's `ToString()` | only with an exception | | `@tr`, `@sp` | trace id and span id as hex | only if an `Activity` was current | Then every property follows at the **top level**: `"TrackingNumber":"CX-1042","WeightKg":31.27`. Note the property keeps its numeric value; only `@r` holds the formatted text. A destructured object becomes a nested JSON object with its type name under `$type`, and a property whose own name starts with `@` is escaped by doubling the sigil, so it cannot be mistaken for a reified field. Each event ends with a newline, so a file or stream is **newline-delimited JSON**. The format's README names the unofficial media type `application/vnd.serilog.clef` for such batches and says absent `@l` means informational. ## One full line Putting it together, the warning above produces this single line (timestamp illustrative): ```json {"@t":"2026-10-07T09:15:02.1234567Z","@mt":"Shipment {TrackingNumber} weighs {WeightKg:0.0} kg","@r":["31.3"],"@l":"Warning","TrackingNumber":"CX-1042","WeightKg":31.27} ``` Add `Enrich.FromLogContext()` and a pushed `CourierId`, and `"CourierId":77` simply appears as another top-level field; an `ILogger<T>` category adds `SourceContext` the same way. ## Why it is compact - one- or two-character names for built-in fields; - properties flattened to the top level instead of a nested object; - the most common level omitted; - renderings only for holes that need them. The README's comparison shows the same event at about two thirds of the bytes of the core `JsonFormatter`. ## The alternatives **`RenderedCompactJsonFormatter`** (same package) writes `@m`, the fully rendered message, instead of `@mt`, plus `@i`, an event id computed as a hash of the template text. Use it when the consumer has no message-template renderer: the readable sentence is ready to display, and `@i` still groups events by template. The trade-off is that the template itself is not in the output. **`JsonFormatter`** in the core `Serilog` package writes descriptive names - `Timestamp`, `Level`, `MessageTemplate`, an optional `RenderedMessage` when constructed with `renderMessage: true`, `TraceId`, `SpanId`, `Exception` - and puts properties under a nested `Properties` object. It always writes the level. Choose it only when a consumer expects that shape. ## Pitfalls when consuming CLEF - **UTC only.** `@t` is converted to UTC, so the original local offset is not in the line; add it as a property if you need it. - **Absent means Information.** A parser that treats a missing `@l` as unknown misclassifies most events. - **Exceptions are text.** `@x` is the exception's `ToString()`, stack trace included, not a structured object. - **Escaped names.** A property that genuinely starts with `@` appears with the sigil doubled, `@@name`. - **Unknown fields are data.** The format is versioned additively, so consumers should treat unrecognised `@` fields as ordinary properties. ## Which one to pick 1. A log store or tool that understands CLEF: `CompactJsonFormatter`. 2. A store that indexes JSON but displays raw fields: `RenderedCompactJsonFormatter`, so people see `@m`. 3. Humans reading a terminal: keep the console's text output template, and use JSON for the file or the shipping sink. In every case the formatter only changes the representation; which properties exist was decided earlier, by the template, the capture operators and the enrichers.
- Why does a CLEF line for an Information event have no @l field?The compact formatters leave out the level when it is `Information`, the most common case, to save bytes. The format defines a missing `@l` as informational, so a consumer must treat absence as Information rather than as unknown.
- {WeightKg:0.0} logs 31.27. What does the CLEF line hold for that property?The `WeightKg` property keeps the number 31.27, and the formatted text "31.3" appears in the `@r` array, one entry per hole that has a format string. Queries work on the real value while a viewer can still reproduce the rendered message.
- CompactJsonFormatter writes the rendered message in @m by default
- @l is always present, Information included
- Format strings change the stored property value to formatted text
- Properties are nested under a Properties object in CLEF
- CompactJsonFormatter ships in the core Serilog package
Assumes Serilog.Formatting.Compact 3.0 on Serilog 4.4; @tr and @sp come from LogEvent.TraceId and SpanId, which Serilog fills from Activity.Current.