9.0.0 Release

README.md

@@ -28,41 +28,41 @@ using Serilog;
 
 public class Startup
 {
-  public Startup(IHostingEnvironment env)
-  {
-    Log.Logger = new LoggerConfiguration()
-      .Enrich.FromLogContext()
-      .WriteTo.Console()
-      .CreateLogger();
-
-    // Other startup code
+    public Startup(IHostingEnvironment env)
+    {
+        Log.Logger = new LoggerConfiguration()
+          .Enrich.FromLogContext()
+          .WriteTo.Console()
+          .CreateLogger();
+
+        // Other startup code
 ```
 
 **Finally, for .NET Core 2.0+**, in your `Startup` class's `Configure()` method, remove the existing logger configuration entries and
 call `AddSerilog()` on the provided `loggingBuilder`.
 
 ```csharp
-  public void ConfigureServices(IServiceCollection services)
-  {
-      services.AddLogging(loggingBuilder =>
-      	loggingBuilder.AddSerilog(dispose: true));
+public void ConfigureServices(IServiceCollection services)
+{
+    services.AddLogging(loggingBuilder =>
+        loggingBuilder.AddSerilog(dispose: true));
 
-      // Other services ...
-  }
+    // Other services ...
+}
 ```
 
 **For .NET Core 1.0 or 1.1**, in your `Startup` class's `Configure()` method, remove the existing logger configuration entries and call `AddSerilog()` on the provided `loggerFactory`.
 
 ```
-  public void Configure(IApplicationBuilder app,
-                        IHostingEnvironment env,
-                        ILoggerFactory loggerfactory,
-                        IApplicationLifetime appLifetime)
-  {
-      loggerfactory.AddSerilog();
-
-      // Ensure any buffered events are sent at shutdown
-      appLifetime.ApplicationStopped.Register(Log.CloseAndFlush);
+public void Configure(IApplicationBuilder app,
+                      IHostingEnvironment env,
+                      ILoggerFactory loggerfactory,
+                      IApplicationLifetime appLifetime)
+{
+    loggerfactory.AddSerilog();
+
+    // Ensure any buffered events are sent at shutdown
+    appLifetime.ApplicationStopped.Register(Log.CloseAndFlush);
 ```
 
 That's it! With the level bumped up a little you should see log output like:
@@ -80,6 +80,19 @@ That's it! With the level bumped up a little you should see log output like:
 [22:14:45.741 DBG] Handled. Status code: 304 File: /css/site.css
 ```
 
+### Including the log category in text-format sink output
+All _Microsoft.Extensions.Logging.ILogger_ implementations are created with a specified [_log category_](https://learn.microsoft.com/en-us/dotnet/core/extensions/logging?tabs=command-line#log-category) string, which is then attached as structured data to each log message created by that `ILogger` instance. Typically, the log category is the fully-qualified name of the class generating the log messages. This convention is implemented by the [`ILogger<TCategoryName>`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger-1) interface, which is commonly used as an injected dependency in frameworks that use _Microsoft.Extensions.Logging_.
+
+_Serilog.Extensions.Logging_ captures the `ILogger`'s log category, but it's not included in the default output templates for text-based sinks, such as [Console](https://github.com/serilog/serilog-sinks-console), [File](https://github.com/serilog/serilog-sinks-file) and [Debug](https://github.com/serilog/serilog-sinks-debug).
+
+To include the log category in the final written messages, add the `{SourceContext}` named hole to a customised `outputTemplate` parameter value when configuring the relevant sink(s). For example:
+```csharp
+.WriteTo.Console(
+    outputTemplate: "[{Timestamp:HH:mm:ss} {Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
+.WriteTo.File("log.txt",
+    outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {SourceContext}: {Message:lj}{NewLine}{Exception}")
+```
+
 ### Notes on Log Scopes
 
 _Microsoft.Extensions.Logging_ provides the `BeginScope` API, which can be used to add arbitrary properties to log events within a certain region of code. The API comes in two forms:
@@ -90,7 +103,8 @@ _Microsoft.Extensions.Logging_ provides the `BeginScope` API, which can be used
 Using the extension method will add a `Scope` property to your log events. This is most useful for adding simple "scope strings" to your events, as in the following code:
 
 ```csharp
-using (_logger.BeginScope("Transaction")) {
+using (_logger.BeginScope("Transaction"))
+{
     _logger.LogInformation("Beginning...");
     _logger.LogInformation("Completed in {DurationMs}ms...", 30);
 }
@@ -102,8 +116,9 @@ using (_logger.BeginScope("Transaction")) {
 If you simply want to add a "bag" of additional properties to your log events, however, this extension method approach can be overly verbose. For example, to add `TransactionId` and `ResponseJson` properties to your log events, you would have to do something like the following:
 
 ```csharp
-// WRONG! Prefer the dictionary approach below instead
-using (_logger.BeginScope("TransactionId: {TransactionId}, ResponseJson: {ResponseJson}", 12345, jsonString)) {
+// WRONG! Prefer the dictionary or value tuple approach below instead
+using (_logger.BeginScope("TransactionId: {TransactionId}, ResponseJson: {ResponseJson}", 12345, jsonString))
+{
     _logger.LogInformation("Completed in {DurationMs}ms...", 30);
 }
 // Example JSON output:
@@ -125,11 +140,13 @@ Moreover, the template string within `BeginScope` is rather arbitrary when all y
 A far better alternative is to use the `BeginScope<TState>(TState state)` method. If you provide any `IEnumerable<KeyValuePair<string, object>>` to this method, then Serilog will output the key/value pairs as structured properties _without_ the `Scope` property, as in this example:
 
 ```csharp
-var scopeProps = new Dictionary<string, object> {
+var scopeProps = new Dictionary<string, object>
+{
     { "TransactionId", 12345 },
     { "ResponseJson", jsonString },
 };
-using (_logger.BeginScope(scopeProps) {
+using (_logger.BeginScope(scopeProps)
+{
     _logger.LogInformation("Transaction completed in {DurationMs}ms...", 30);
 }
 // Example JSON output:
@@ -144,6 +161,25 @@ using (_logger.BeginScope(scopeProps) {
 // }
 ```
 
+Alternatively provide a `ValueTuple<string, object?>` to this method, where `Item1` is the property name and `Item2` is the property value.
+Note that `T2` _must_ be `object?` if your target platform is net462 or netstandard2.0.
+
+```csharp
+using (_logger.BeginScope(("TransactionId", 12345))
+{
+    _logger.LogInformation("Transaction completed in {DurationMs}ms...", 30);
+}
+// Example JSON output:
+// {
+//	"@t":"2020-10-29T19:05:56.4176816Z",
+//	"@m":"Completed in 30ms...",
+//	"@i":"51812baa",
+//	"DurationMs":30,
+//	"SourceContext":"SomeNamespace.SomeService",
+//	"TransactionId": 12345
+// }
+```
+
 ### Versioning
 
 This package tracks the versioning and target framework support of its [_Microsoft.Extensions.Logging_](https://nuget.org/packages/Microsoft.Extensions.Logging) dependency.

appveyor.yml

@@ -12,7 +12,7 @@ artifacts:
 deploy:
 - provider: NuGet
   api_key:
-    secure: EN9f+XXE3fW+ebL4wxrIbafdtbNvRfddBN8UUixvctYh4qMBHzr1JdnM83QsM1zo
+    secure: H96ajkMxwIafhF2vrr+UAUS10bFcAL/1wc3iphidRiYi9WoTc2i8shTLtF+75ODb
   skip_symbols: true
   on:
     branch: /^(main|dev)$/

samples/SampleWithExternalScope/Program.cs

@@ -0,0 +1,56 @@
+using System.Diagnostics;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Logging;
+using Serilog;
+using Serilog.Formatting.Json;
+
+// Configure a JsonFormatter to log out scope to the console
+Log.Logger = new LoggerConfiguration()
+    .MinimumLevel.Debug()
+    .WriteTo.Console(new JsonFormatter())
+    .CreateLogger();
+
+// Setup Serilog with M.E.L, and configure the appropriate ActivityTrackingOptions
+var services = new ServiceCollection();
+
+services.AddLogging(l => l
+    .AddSerilog()
+    .Configure(options =>
+    {
+        options.ActivityTrackingOptions =
+            ActivityTrackingOptions.SpanId
+            | ActivityTrackingOptions.TraceId
+            | ActivityTrackingOptions.ParentId
+            | ActivityTrackingOptions.TraceState
+            | ActivityTrackingOptions.TraceFlags
+            | ActivityTrackingOptions.Tags
+            | ActivityTrackingOptions.Baggage;
+    }));
+
+// Add an ActivityListener (required, otherwise Activities don't actually get created if nothing is listening to them)
+ActivitySource.AddActivityListener(new ActivityListener
+{
+    ShouldListenTo = source => true,
+    Sample = (ref ActivityCreationOptions<ActivityContext> options) => ActivitySamplingResult.AllDataAndRecorded
+});
+
+// Run our test
+var activitySource = new ActivitySource("SomeActivitySource");
+
+var serviceProvider = services.BuildServiceProvider();
+var logger = serviceProvider.GetRequiredService<ILogger<Program>>();
+
+using var activity = activitySource.StartActivity();
+
+activity?.SetTag("tag.domain.id", 1234);
+activity?.SetBaggage("baggage.environment", "uat");
+
+using var scope = logger.BeginScope(new
+{
+    User = "Hugh Mann",
+    Time = DateTimeOffset.UtcNow
+});
+
+logger.LogInformation("Hello world!");
+
+serviceProvider.Dispose();

samples/SampleWithExternalScope/SampleWithExternalScope.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <OutputType>Exe</OutputType>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\Serilog.Extensions.Logging\Serilog.Extensions.Logging.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
+    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="8.0.0" />
+    <PackageReference Include="Serilog.Sinks.Console" Version="5.0.0" />
+  </ItemGroup>
+
+</Project>

serilog-extensions-logging.sln

@@ -31,6 +31,8 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "assets", "assets", "{9C21B9
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Serilog.Extensions.Logging.Benchmarks", "test\Serilog.Extensions.Logging.Benchmarks\Serilog.Extensions.Logging.Benchmarks.csproj", "{6D5986FF-EECD-4E75-8BC6-A5F78AB549B2}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "SampleWithExternalScope", "samples\SampleWithExternalScope\SampleWithExternalScope.csproj", "{653092A8-CBAD-40AA-A4CE-F8B19D6492C2}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -53,6 +55,10 @@ Global
 		{6D5986FF-EECD-4E75-8BC6-A5F78AB549B2}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{6D5986FF-EECD-4E75-8BC6-A5F78AB549B2}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{6D5986FF-EECD-4E75-8BC6-A5F78AB549B2}.Release|Any CPU.Build.0 = Release|Any CPU
+		{653092A8-CBAD-40AA-A4CE-F8B19D6492C2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{653092A8-CBAD-40AA-A4CE-F8B19D6492C2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{653092A8-CBAD-40AA-A4CE-F8B19D6492C2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{653092A8-CBAD-40AA-A4CE-F8B19D6492C2}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -62,6 +68,7 @@ Global
 		{37EADF84-5E41-4224-A194-1E3299DCD0B8} = {E30F638E-BBBE-4AD1-93CE-48CC69CFEFE1}
 		{65357FBC-9BC4-466D-B621-1C3A19BC2A78} = {F2407211-6043-439C-8E06-3641634332E7}
 		{6D5986FF-EECD-4E75-8BC6-A5F78AB549B2} = {E30F638E-BBBE-4AD1-93CE-48CC69CFEFE1}
+		{653092A8-CBAD-40AA-A4CE-F8B19D6492C2} = {F2407211-6043-439C-8E06-3641634332E7}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {811E61C5-3871-4633-AFAE-B35B619C8A10}

src/Serilog.Extensions.Logging/Extensions/Logging/EventIdPropertyCache.cs

@@ -0,0 +1,97 @@
+// Copyright (c) Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+namespace Serilog.Extensions.Logging;
+
+using System.Collections.Concurrent;
+using Microsoft.Extensions.Logging;
+using Serilog.Events;
+
+class EventIdPropertyCache
+{
+    readonly int _maxCachedProperties;
+    readonly ConcurrentDictionary<EventKey, LogEventProperty> _propertyCache = new();
+
+    int _count;
+
+    public EventIdPropertyCache(int maxCachedProperties = 1024)
+    {
+        _maxCachedProperties = maxCachedProperties;
+    }
+
+    public LogEventProperty GetOrCreateProperty(in EventId eventId)
+    {
+        var eventKey = new EventKey(eventId);
+
+        LogEventProperty? property;
+
+        if (_count >= _maxCachedProperties)
+        {
+            if (!_propertyCache.TryGetValue(eventKey, out property))
+            {
+                property = CreateProperty(in eventKey);
+            }
+        }
+        else
+        {
+            if (!_propertyCache.TryGetValue(eventKey, out property))
+            {
+                // GetOrAdd is moved to a separate method to prevent closure allocation
+                property = GetOrAddCore(in eventKey);
+            }
+        }
+
+        return property;
+    }
+
+    static LogEventProperty CreateProperty(in EventKey eventKey)
+    {
+        var properties = new List<LogEventProperty>(2);
+
+        if (eventKey.Id != 0)
+        {
+            properties.Add(new LogEventProperty("Id", new ScalarValue(eventKey.Id)));
+        }
+
+        if (eventKey.Name != null)
+        {
+            properties.Add(new LogEventProperty("Name", new ScalarValue(eventKey.Name)));
+        }
+
+        return new LogEventProperty("EventId", new StructureValue(properties));
+    }
+
+    LogEventProperty GetOrAddCore(in EventKey eventKey) =>
+        _propertyCache.GetOrAdd(
+            eventKey,
+            key =>
+            {
+                Interlocked.Increment(ref _count);
+
+                return CreateProperty(in key);
+            });
+
+    readonly record struct EventKey
+    {
+        public EventKey(EventId eventId)
+        {
+            Id = eventId.Id;
+            Name = eventId.Name;
+        }
+
+        public int Id { get; }
+
+        public string? Name { get; }
+    }
+}