What's Changed

• #2141 — stabilize and fully implement dotted identifiers in message templates (@nblumhardt)
• #2028 — use RuntimeHelpers.GetHashCode() in message template cache comparer (@sungam3r)
• #2138 — update to .NET 9 SDK, GitHub Actions build, net9.0 TFM (@nblumhardt)
• #2132 — support capturing of multidimensional arrays (@sungam3r, @WAcry)
• #2136 — fix documentation for ILogEventSink (@erichiller)

New Contributors

• @WAcry made their first contribution in #2132

Full Changelog: v4.1.0...v4.2.0

• #2108 - failure listeners and fallback sinks (@nblumhardt)
• #2120 - add BatchingOptions.RetryTimeLimit and update retry scheduling algorithm (@nblumhardt)

Important note

IBatchedLogEventSink batch retry scheduling has changed in this version. The default configuration still tries failed batches for approximately ten minutes, but the BufferingTimeLimit no longer implicitly causes the retry time to be extended or reduced. If you need a specific retry time, set BatchingOptions.RetryTimeLimit, which reliably controls retry time.

• #2094 - remove boxing and string allocations in output template formatting (@epeshk)
• #2103 - don't capture properties with private get accessors (@nblumhardt)
• #2095 - remove junk file (@Numpsy)
• #2116 - fall back to IDisposable in Log.CloseAndFlushAsync() when the target logger is not IAsyncDisposable (@nblumhardt)

• #2090 — when capturing structured values, reuse HashSet instances, reduce LINQ usage, avoid reallocating string[] to improve performance and cut GC pressure (@nblumhardt)
• #2089 - allow capturing of non-anonymous structured values when trimming (@nblumhardt)
• #2083 - use Major.Minor.0.0 assembly versioning (@nblumhardt)

What's new in Serilog 4.0.0?

If you're deploying to .NET Framework, note that Serilog's assembly version number has been unpinned from the long-running historical 2.0.0 default, and now matches the package version precisely. If you encounter issues, ensure your build is generating valid assembly binding redirects.

Simple, robust, built-in batching support

Sinks that need batching functionality can now be easily written, without any additional package dependencies, by implementing IBatchedLogEventSink:

class MyBatchedSink: IBatchedLogEventSink
{
    public Task EmitBatchAsync(IReadOnlyCollection<LogEvent> batch)
    {
        // Send a batch of log events...
    }
}

Batched sinks can be added using WriteTo.Sink(IBatchedLogEventSink, ...) - they're given first-class consideration just like regular un-batched sinks.

The built-in batching implementation is based on System.Threading.Channels and draws on the original Serilog.Sinks.PeriodicBatching package (now in maintenance-mode), to provide a full-featured, efficient, async-native batching implementation.

Experimental dotted name capturing

By setting an experimental AppContext switch, message templates can be used to capture dotted names, which are required when using some logging schemas.

AppContext.SetSwitch("Serilog.Parsing.MessageTemplateParser.AcceptDottedPropertyNames", true);

Log.Information("Running as {user.name}", Environment.UserName);
// Captures {"user.name": "nblumhardt"}

While currently experimental and unsupported, this flag is intended to help the ecosystem evaluate and prepare for dotted name support in a future Serilog release.

Changes

• #2015 — breaking unpin assembly version (@nblumhardt)
• #2045 — breaking use case-insensitive matching for level overrides (@tillig)
• #2051 — breaking recognize UtcTimestamp as a built-in token in output templates (@MatthewHays)
• #1979 — add tests for ReusableStringWriter (@nblumhardt)
• #2016 — update TFMs (@nblumhardt, @bartelink)
• #2018 — add LogEvent.UnstableAssembleFromParts() (@nblumhardt)
• #2044 — build updates for compatibility (@tillig)
• #2027 — improve trimming annotations, compatibility switch for compiler-generated type support (@agocke)
• #2055 — introduce IBatchedLogEventSink and WriteTo.Sink(IBatchedLogEventSink) (@nblumhardt)
• #2060 — introduce LoggerSinkConfiguration.CreateSink() and redesign .Wrap() (@nblumhardt, @bartelink)
• #2063 — improve MessageTemplateParser performance, switch to allow . in captured property names (@nblumhardt)
• #2064 — make message template alignment parsing match spec (@Insomniak47)
• #2065 — allow any character except } in message template format specifiers (@Insomniak47)

• #1977 - don't stack overflow when disposing ReusableStringWriter with large renderings (@nblumhardt)

This is a bugfix for release 3.1.0.

• #1935 - remove CHANGES.md (@sungam3r)
• #1936, #1922 - README.md updates (@nblumhardt)
• #1942 - remove redundant GetTypeInfo() calls (@SimonCropp)
• #1947 - message template caching performance improvements (@epeshk)
• #1948 - reduce allocations in Logger.Write() (@epeshk)
• #1955 breaking - collect and propagate Activity.Current.TraceId and SpanId automatically in Logger.Write() (@nblumhardt)
• #1959 - breaking - property value converter optimizations (@epeshk)
• #1964 - don't cache reusable string writers with large buffer sizes (@Jakimar)
• #1969 - README.md updates (@bartelink)
• #1971 - drop test coverage for unsupported .NET Core versions (@bartelink)

Built-in trace and span id support

This release adds two new first-class properties to LogEvent: TraceId and SpanId. These are set automatically in Logger.Write() to the corresponding property values from System.Diagnostics.Activity.Current.

The major benefit of this change is that sinks, once updated, can reliably propagate trace and span ids through to back-ends that support them (in much the same way that first-class timestamps, messages, levels, and exceptions are used today).

The sinks maintained under serilog/serilog, along with formatting helpers such as Serilog.Formatting.Compact and Serilog.Expressions, are already compatible with this change or have pending releases that add compatibility.

Dropped .NET Core 2.1 and 3.0 support

On .NET Core 2.1 and 3.0, projects targeting Serilog 3.1+ will fail to build, with:

/project/packages/system.runtime.compilerservices.unsafe/6.0.0/buildTransitive/netcoreapp2.0
/System.Runtime.CompilerServices.Unsafe.targets(4,5): error : System.Runtime.CompilerServices.Unsafe
doesn't support netcoreapp2.1. Consider updating your TargetFramework to netcoreapp3.1 or later.

Affected consumers should continue to use Serilog 3.0 or earlier. See #1983 for a discussion of this issue.

Technical breaking changes

Trace and span id placeholders

Trace and span id collection includes support for {TraceId} and {SpanId} placeholders in output templates (commonly used when formatting text log files). Where previously these names resolved to user-defined properties, they now resolve to the built-in LogEvent.TraceId and LogEvent.SpanId values, respectively.

Impact is expected to be low/zero, because the trace and span id values in any user-added properties are almost certainly identical to the built-in ones.

nint and nuint (IntPtr and UIntPtr) handling

These integer types were previously logged as structures. They're now correctly logged as scalars.

• #1926 - fix JsonFormatter output for renderMessage = true (@nblumhardt)

What's new in 3.0.0?

Target framework changes - Serilog no longer targets netstandard1.x or .NET Framework versions earlier than .NET 4.6.2. Users on affected frameworks should continue to target Serilog 2.12.x.

Removed obsolete APIs - Many deprecated/obsolete types and functions have been removed. Notably, JsonFormatter can no longer be subclassed (either port to JsonValueFormatter, use Serilog.Expressions, or copy the original JsonFormatter code into your project).

Added APIs - LevelAlias.Off is now provided as an equivalent to Microsoft.Extensions.Logging's LogLevel.Off; Destructure.AsDictionary<T>() can now be used to mark dictionary types.

Fewer allocations on many hot paths - A lot of work has gone into avoiding heap allocations wherever possible.

Changes

• Change exception message by @sungam3r in #1762
• Avoided IEnumerator allocation (#1769) by @igor84 in #1770
• Avoid iterator allocations when working with SequenceValue by @sungam3r in #1785
• Add API approval test by @sungam3r in #1783
• Bump Newtonsoft.Json from 13.0.1 to 13.0.2 in /test/Serilog.Tests by @dependabot in #1787
• Introduce ScalarValue.Null by @sungam3r in #1774
• Tokens -> TokenArray by @sungam3r in #1778
• Drop netstandard1.3 and netstandard1.0 support by @SimonCropp in #1807
• Remove JsonFormatter.Escape by @SimonCropp in #1804
• Use WriteLine(char) by @SimonCropp in #1803
• Remove extension of JsonFormatter by subclassing by @SimonCropp in #1801
• Remove redundant overrides from LoggerSinkConfiguration by @SimonCropp in #1800
• Avoid StringWriter.ToString() calls by @sungam3r in #1782
• Remove the obsolete RawFormatter type by @nblumhardt in #1808
• .NET 7 SDK by @SimonCropp in #1806
• Remove OutputProperties.GetOutputProperties() by @SimonCropp in #1805
• Verify API by @SimonCropp in #1809
• Remove redundant nullable suppressions by @SimonCropp in #1810
• Remove duplicate Where() calls in FindConfigurationMethods() by @SimonCropp in #1812
• Remove net45 support by @SimonCropp in #1811
• Remove redundant GetTypeInfo() in LoadConfigurationAssemblies by @SimonCropp in #1817
• Remove GetTypeInfo() from FindConfigurationMethods(() by @SimonCropp in #1815
• Remove redundant GetTypeInfo() in EnumScalarConversionPolicy by @SimonCropp in #1816
• Remove obsolete PropertyToken constructor by @SimonCropp in #1819
• switch expressions by @SimonCropp in #1818
• Do not allocate strings for TextWriter.Write() by @sungam3r in #1775
• Simplify reflection in SettingValueConversions by @SimonCropp in #1814
• Improve GetPropertiesRecursive() performance by @SimonCropp in #1813
• Use Convert.ToHexString() in ByteArrayScalarConversionPolicy() by @sungam3r in #1776
• Remove FEATURE_ASYNCLOCAL by @SimonCropp in #1822
• Remove FEATURE_HASHTABLE by @SimonCropp in #1823
• Use IsEnum for enum check in EnumScalarConversionPolicy by @SimonCropp in #1825
• Comments on Hashtable use in MessageTemplateCache by @SimonCropp in #1828
• Remove GetTypeInfo() from PropertyValueConverter by @SimonCropp in #1824
• Avoid repeated GetType() in PropertyValueConverter by @SimonCropp in #1832
• Leverage dictionary TryAdd() and items constructor by @SimonCropp in #1830
• Use array instead of list when we know the size in PropertyValueConverter by @SimonCropp in #1831
• Move net46 target to net461 by @SimonCropp in #1827
• Clean up JsonValueFormatter by @SimonCropp in #1835
• var in JsonFormatter by @SimonCropp in #1838
• Remove obsolete SelfLog.Out by @SimonCropp in #1837
• Remove obsolete JsonFormatter omitEnclosingObject overload by @SimonCropp in #1834
• Remove obsolete PushProperties() by @SimonCropp in #1836
• No point putting _minimumLevel and _levelSwitch on stack by @SimonCropp in #1840
• Avoid casting enum to int where possible by @SimonCropp in #1841
• Leverage nullable char in JsonFormatter by @SimonCropp in #1839
• Use correct overload with char in JsonFormatter by @sungam3r in #1842
• Annotate Serilog for trimming by @agocke in #1690
• Fix net471 DisableImplicitFrameworkReferences by @SimonCropp in #1846
• Fix 461 TargetFramework constants in tests by @SimonCropp in #1847
• Missing API approval by @SimonCropp in #1848
• net471 supports ITuple by @SimonCropp in #1849
• Remove FEATURE_GETCURRENTMETHOD const by @SimonCropp in #1851
• macOS CI by @SimonCropp in #1858
• Run tests on mac by @SimonCropp in #1860
• BenchmarkDotNet 0.13.5 by @SimonCropp in #1861
• Cache empty text token by @SimonCropp in #1859
• Simplify PublicApi_Should_Not_Change_Unintentionally() test by @SimonCropp in #1864
• Move from net461 to net462 by @SimonCropp in #1863
• Remove redundant GetPackagingOutputs by @SimonCropp in #1867
• Use char delimiters by @SimonCropp in #1868
• Remove redundant reference assemblies by @SimonCropp in #1866
• Introduce PolySharp by @sungam3r in #1845
• Missing PolySharp changes by @SimonCropp in #1869
• Simplify build scripts by @SimonCropp in #1865
• Added ReusableStringWriter by @igor84 in #1771
• PublicApiGenerator v11 by @SimonCropp in #1877
• Use langword in XML comments by @sungam3r in #1871
• Avoid creating SafeAggregateSink wrapper around empty list by @sungam3r in #1878
• Remove obsolete classes by @sungam3r in #1874
• Add space settings by @sungam3r in #1885
• Make Alignment and LevelOverrides readonly by @sungam3r in #1884
• Remove redundant CallerArgumentExpressionAttribute by @SimonCropp in #1886
• Remove MessageTemplateToken.StartIndex by @SimonCropp in #1882
• Microsoft.NET.Test.Sdk 17.5.0 by @SimonCropp in #1862
• Throw, rather than exit, when any command in the build script fails by @nblumhardt in #1887
• Suppress some warnings, tidy up some namespacing by @nblumhardt in #1888
• Reinstate LoggerSinkConfiguration.Sink(ILogEventSink, LogEventLevel) by @nblumhardt in #1889
• Avoid some alloc with Array.Empty by @SimonCropp in #1898
• Destructure ReadOnlyDictionary as Dictionary by @sungam3r in #1897
• Remove redundant IDictionary cast by @SimonCropp in #1900
• Adding ability to dispose nested loggers in WriteTo.Logger() by @srogovtsev in #1890
• Optimize AddPropertyIfAbsent by @sungam3r in #1872
• Accept/pass through the standard levelSwitch option in WriteTo.Logger() by @nblumhardt in #1902
• Add net47 target by @SimonCropp in #1905
• Annotate WithProperty() by @sun...

Highlights of 2.12.0

Improved and expanded <Nullable>enable</Nullable> support

A huge number of commits have gone into completing and refining non-null reference type annotations, which now cover the entire public Serilog API. The Serilog project itself now builds with non-null reference type checking globally enabled 🎉

IAsyncDisposable support

Sinks that need to flush changes using asynchronous APIs can now implement IAsyncDisposable and prevent the possibility of deadlocking while waiting for tasks to complete.

To drive this, Logger can now be disposed via using async:

await using var log = new LoggerConfiguration().CreateLogger();

and the Log class provides Log.CloseAndFlushAsync():

await Log.CloseAndFlushAsync();

DateOnly and TimeOnly support

The DateOnly and TimeOnly types introduced in .NET 6 are now correctly handled as scalar values when capturing.

Merged PRs

• #1713, #1716, #1715, #1722, #1721, #1720, #1729 - improved non-null reference type annotations (@SimonCropp)
• #1702 - DateOnly and TimeOnly support (@SimonCropp)
• #1764, #1703, #1708, #1709, #1712, #1724, #1730, #1747 - build and dependency updates (@SimonCropp)
• #1723, #1728, #1731, #1732, #1734, #1735, #1733, #1736, #1739, #1746, #1745, #1741, #1742 - code clean-up and modernization (@SimonCropp)
• #1750 - IAsyncDisposable support for Logger and sinks (@nblumhardt)
• #1699 - fix some XDOC documentation (@sungam3r)
• #1719 - remove redundant ! operator from null in conditions (@sungam3r)
• #1725 - introduce file-scoped namespaces (@sungam3r)
• #1700, #1704, #1707 - more nulllable annotation updates (@nblumhardt)
• #1711 - fix support for ValueTuple (@SimonCropp)