In a Serilog message template, how do {Shipment}, {@Shipment} and {$Shipment} differ, and what does @ cost on a large object?
answer
- default: scalars, collections, else ToString()
- @ = reflection over public properties
- $ = always ToString()
- destructuring depth limit 10
- getters run at log time
basics
~10 sPlain {Shipment} keeps scalars and collections but stores ToString() for other objects; {@Shipment} destructures public properties recursively, to depth 10; {$Shipment} always stores ToString(). @ costs reflection, every getter run, and graph-sized payloads.
solid answer
~40 sWith a plain `{Shipment}`, Serilog keeps **scalars** as typed values (numbers, `string`, `decimal`, `DateTime`, `DateTimeOffset`, `TimeSpan`, `Guid`, `Uri`, enums), turns collections into sequences or dictionaries, and calls `ToString()` on anything else - for a class without an override that is just its type name. `{@Shipment}` asks for **destructuring**: configured policies such as `Destructure.ByTransforming<T>` are tried first, then Serilog reads every public instance property by reflection and recurses with `@` semantics, stopping at a depth of 10. `{$Shipment}` forces `ToString()` even for collections. The price of `@` is paid on the logging thread for every enabled event: reflection over the graph, every getter executed (including expensive or lazy-loading ones), unbounded collections by default, larger payloads - and every personal field the object happens to carry.
go deeper
Know that {@Shipment} logs the object's properties, {Shipment} usually logs only ToString(), and {$Shipment} always logs ToString().
Explain the capture order - scalars, collections, ToString - versus destructuring through policies and reflection, the type tag and the depth limit of 10.
Weigh @ against getter side effects, lazy-loading entities, unbounded collections and personal data, and log identifiers or transformed shapes instead.
Set a team rule for what may be destructured in logs, backed by transformation policies, so log size and data exposure stay predictable.
## Three ways to capture one value A message template hole can carry a **capture operator** in front of the name. It tells Serilog how to turn the argument into a property value: | Hole | Name | Result for a `Shipment` class instance | |---|---|---| | `{Shipment}` | default | `ToString()` - often just `Courier.Shipments.Shipment` | | `{@Shipment}` | destructure | a structure with each public property, nested objects destructured too | | `{$Shipment}` | stringify | `ToString()`, always, whatever the type | The operator only matters for values that are not already simple. ## What the default capture does Serilog's `PropertyValueConverter` follows a fixed order: 1. `null` stays null and `string` stays a string. 2. **Scalar policies**: primitives, `decimal`, `DateTime`, `DateTimeOffset`, `TimeSpan`, `Guid`, `Uri`, `DateOnly`, `TimeOnly`, enums and byte arrays become typed scalars. Types registered with `Destructure.AsScalar<T>()` join this list. 3. **Collections**: any `IEnumerable` becomes a sequence (or a dictionary for dictionary types), with each element captured by the same rules - so a `List<Shipment>` without `@` is a list of type names. 4. Value tuples become sequences. 5. Anything else: `ToString()`. So `{Parcels}` for a `List<int>` already logs `[3, 7, 12]` with no operator, while `{Shipment}` for a class does not show its data unless the class overrides `ToString()`. ## What @ does With `@`, step 5 is replaced by destructuring: - Configured destructuring policies run first - `Destructure.ByTransforming<T>`, `Destructure.With(policy)` - and the first one that accepts the value wins. - Otherwise Serilog builds a `StructureValue` from the public, readable instance properties (inherited ones included, indexers skipped), and records the type name as a **type tag**. Compact JSON writes that tag as `$type`; anonymous types get none. - Every nested property is captured with destructuring semantics, so a `Recipient` inside the shipment becomes a nested structure. - At a depth of **10** property traversals the converter stops, stores null and writes "Maximum destructuring depth reached." to `SelfLog` - the guard against cyclic graphs. - A getter that throws does not fail the call; the property gets a text value saying the accessor threw. ## What @ costs The capture happens **synchronously, when the event is created**, not later in the sink - the object might change after the call returns. For every enabled event: - **CPU**: reflection over every property of every object in the graph. - **Side effects**: every getter runs. A computed property doing I/O, or an ORM entity with lazy-loading navigation properties, can trigger work or queries just because it was logged. - **Size**: by default strings and collections are not limited (`ToMaximumStringLength` and `ToMaximumCollectionCount` default to `int.MaxValue`), so a shipment with 5,000 scan events produces a 5,000-element array in every log line. - **Data exposure**: the recipient's name, phone number and address go wherever your logs go. Level checks still apply first: if the event's level is disabled, no capture work is done. ## What it looks like in JSON With a compact JSON formatter, `Log.Information("Shipment updated {@Shipment}", shipment)` produces a nested object tagged with its type: ```json {"@t":"2026-10-07T09:15:02.1234567Z","@mt":"Shipment updated {@Shipment}","Shipment":{"TrackingNumber":"CX-1042","Status":"InTransit","Recipient":{"Name":"A. Customer","Phone":"+1 555 0100","$type":"Recipient"},"$type":"Shipment"}} ``` The same call with `{Shipment}` stores `"Shipment":"Courier.Shipments.Shipment"`, and with `{$Shipment}` stores whatever `ToString()` returns. Two things stand out in the destructured version: the enum `Status` is a scalar string, and the recipient's personal data is now in the log, exactly as the object held it. ## Choosing in a courier API ```csharp // a small, stable DTO: destructuring is the point Log.Information("Quote calculated {@Quote}", quote); // a rich entity: log the identifiers you will search for Log.Information("Shipment {TrackingNumber} changed to {Status}", s.TrackingNumber, s.Status); // a type whose ToString() is meaningful: force the string Log.Warning("Unexpected depot {$Depot}", depot); ``` The rule of thumb: use `@` on small, purpose-built objects; log entities through chosen scalar properties or through a destructuring transformation that limits them.
- Does Destructure.ByTransforming<Shipment> change what {Shipment} without @ logs?No. Destructuring policies are only consulted when destructuring was requested, by `@` or `destructureObjects: true`. A plain `{Shipment}` still goes through the scalar, collection and `ToString()` path, so an overridden `ToString()` that prints the recipient leaks it regardless of the transformation.
- Why would {@Shipment} log null for a deeply nested property and how do you confirm it?The destructuring depth limit (10 by default) was reached, usually because of a cycle such as Shipment to Courier to Shipments. Serilog stores null at that point and writes "Maximum destructuring depth reached." to `SelfLog`, so enabling `SelfLog` shows it. Fix the shape you log rather than raising the limit.
Default capture is noting a parcel's label; @ is opening the box and photographing every item inside, nested boxes included; $ is writing down whatever the sender scribbled on the outside. Opening every box is thorough, slow, and shows whatever private items happen to be inside.
- {Shipment} without @ logs every public property of the object
- @ serialises the object later, in the sink, so it costs nothing on the request
- {$Shipment} destructures the object and then converts the result to a string
- Collections are only captured as arrays when you use @
- Destructuring stops at the first nested object, so cycles cannot happen