Upgrading from v8 to v9

v9 is a major release. This page is the practical checklist; see Breaking changes for the exhaustive list.

1. Prerequisites

• Move to net8.0, net9.0 or net10.0 (older targets are dropped)
• Serilog 4.3.1+ is required
• FSharp.Core arrives as a transitive dependency - nothing to do, just expect it in your output folder

2. Update appsettings.json

v8	v9
batchPostingLimit	batchSizeLimit
reservedPropertyRenamingStrategy	removed
useInternalTimestamp	removed

Also: queueLimit is now bounded at 50000 by default.

3. Update code

• Custom HTTP client: replace any ILokiHttpClient / LokiGzipHttpClient implementation with a DelegatingHandler (or an injected HttpClient). See Custom HttpClient.
• level label is now optional: v8 added it automatically; v9 keeps it on by default but lets you disable it with handleLogLevelAsLabel: false.
• Fatal value changed: the level value for Fatal is now fatal (was critical). Update Grafana dashboards and alert rules.
• Promoted properties stay in the body: properties listed in propertiesAsLabels now appear both as labels and inside the JSON line. If you relied on them being stripped from the body, adjust your queries.
• Reserved-property renaming is gone: there is no renaming strategy; a body property whose name collides with a reserved key is prefixed with _ (e.g. _Message).

4. Optionally adopt new features

• Trace correlation: traceIdMode / spanIdMode → Trace and span enrichment
• Structured metadata: propertiesAsStructuredMetadata → Structured metadata
• Custom exception output: exceptionFormatter → Custom exception formatting

5. Verify

Enable SelfLog during the cutover to catch rejected batches or misconfiguration:

Serilog.Debugging.SelfLog.Enable(Console.Error);