feat(logs): Sentry.Extensions.Logging

Flash0ver · Flash0ver · commit 8d034494d081 · 2025-05-16T21:37:09.000+02:00
diff --git a/samples/Sentry.Samples.ME.Logging/Program.cs b/samples/Sentry.Samples.ME.Logging/Program.cs
@@ -19,7 +19,17 @@
         // Optionally configure options: The default values are:
         options.MinimumBreadcrumbLevel = LogLevel.Information; // It requires at least this level to store breadcrumb
         options.MinimumEventLevel = LogLevel.Error; // This level or above will result in event sent to Sentry
+        options.MinimumLogLevel = LogLevel.Trace; // This level or above will result in log sent to Sentry
 
+        // This option enables the (experimental) Sentry Logs.
+        options.EnableLogs = true;
+        options.SetBeforeSendLog(static log =>
+        {
+            log.SetAttribute("attribute-key", "attribute-value");
+            return log;
+        });
+
+        // TODO: AddLogEntryFilter
         // Don't keep as a breadcrumb or send events for messages of level less than Critical with exception of type DivideByZeroException
         options.AddLogEntryFilter((_, level, _, exception) => level < LogLevel.Critical && exception is DivideByZeroException);
 
diff --git a/src/Sentry.Extensions.Logging/BindableSentryLoggingOptions.cs b/src/Sentry.Extensions.Logging/BindableSentryLoggingOptions.cs
@@ -7,13 +7,16 @@ internal class BindableSentryLoggingOptions : BindableSentryOptions
 {
     public LogLevel? MinimumBreadcrumbLevel { get; set; }
     public LogLevel? MinimumEventLevel { get; set; }
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public LogLevel? MinimumLogLevel { get; set; }
     public bool? InitializeSdk { get; set; }
 
     public void ApplyTo(SentryLoggingOptions options)
     {
         base.ApplyTo(options);
         options.MinimumBreadcrumbLevel = MinimumBreadcrumbLevel ?? options.MinimumBreadcrumbLevel;
         options.MinimumEventLevel = MinimumEventLevel ?? options.MinimumEventLevel;
+        options.MinimumLogLevel = MinimumLogLevel ?? options.MinimumLogLevel;
         options.InitializeSdk = InitializeSdk ?? options.InitializeSdk;
     }
 }
diff --git a/src/Sentry.Extensions.Logging/LoggingBuilderExtensions.cs b/src/Sentry.Extensions.Logging/LoggingBuilderExtensions.cs
@@ -51,13 +51,21 @@ internal static ILoggingBuilder AddSentry<TOptions>(
 
         builder.Services.AddSingleton<IConfigureOptions<TOptions>, SentryLoggingOptionsSetup>();
         builder.Services.AddSingleton<ILoggerProvider, SentryLoggerProvider>();
+        builder.Services.AddSingleton<ILoggerProvider, SentryStructuredLoggerProvider>();
         builder.Services.AddSentry<TOptions>();
 
         // All logs should flow to the SentryLogger, regardless of level.
         // Filtering of events is handled in SentryLogger, using SentryOptions.MinimumEventLevel
         // Filtering of breadcrumbs is handled in SentryLogger, using SentryOptions.MinimumBreadcrumbLevel
         builder.AddFilter<SentryLoggerProvider>(_ => true);
 
+        // Logs from the SentryLogger should not flow to the SentryStructuredLogger as this may cause recursive invocations.
+        // Filtering of logs is handled in SentryStructuredLogger, using SentryOptions.MinimumLogLevel
+        builder.AddFilter<SentryStructuredLoggerProvider>(static (string? categoryName, LogLevel logLevel) =>
+        {
+            return categoryName is null || !categoryName.StartsWith("Sentry");
+        });
+
         return builder;
     }
 }
diff --git a/src/Sentry.Extensions.Logging/SentryLoggingOptions.cs b/src/Sentry.Extensions.Logging/SentryLoggingOptions.cs
@@ -11,7 +11,9 @@ public class SentryLoggingOptions : SentryOptions
     /// <summary>
     /// Gets or sets the minimum breadcrumb level.
     /// </summary>
-    /// <remarks>Events with this level or higher will be stored as <see cref="Breadcrumb"/></remarks>
+    /// <remarks>
+    /// Events with this level or higher will be stored as <see cref="Breadcrumb"/>.
+    /// </remarks>
     /// <value>
     /// The minimum breadcrumb level.
     /// </value>
@@ -21,13 +23,26 @@ public class SentryLoggingOptions : SentryOptions
     /// Gets or sets the minimum event level.
     /// </summary>
     /// <remarks>
-    /// Events with this level or higher will be sent to Sentry
+    /// Events with this level or higher will be sent to Sentry.
     /// </remarks>
     /// <value>
     /// The minimum event level.
     /// </value>
     public LogLevel MinimumEventLevel { get; set; } = LogLevel.Error;
 
+    /// <summary>
+    /// Gets or sets the minimum log level.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <remarks>
+    /// Logs with this level or higher will be stored as <see cref="SentryLog"/>.
+    /// </remarks>
+    /// <value>
+    /// The minimum log level.
+    /// </value>
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public LogLevel MinimumLogLevel { get; set; } = LogLevel.Trace;
+
     /// <summary>
     /// Whether to initialize this SDK through this integration
     /// </summary>
diff --git a/src/Sentry.Extensions.Logging/SentryStructuredLogger.cs b/src/Sentry.Extensions.Logging/SentryStructuredLogger.cs
@@ -0,0 +1,96 @@
+using Microsoft.Extensions.Logging;
+
+namespace Sentry.Extensions.Logging;
+
+[Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+internal sealed class SentryStructuredLogger : ILogger
+{
+    private readonly string _categoryName;
+    private readonly SentryLoggingOptions _options;
+    private readonly IHub _hub;
+
+    internal SentryStructuredLogger(string categoryName, SentryLoggingOptions options, IHub hub)
+    {
+        _categoryName = categoryName;
+        _options = options;
+        _hub = hub;
+    }
+
+    public IDisposable? BeginScope<TState>(TState state) where TState : notnull
+    {
+        return NullDisposable.Instance;
+    }
+
+    public bool IsEnabled(LogLevel logLevel)
+    {
+        return _hub.IsEnabled
+            && _options.EnableLogs
+            && logLevel != LogLevel.None
+            && logLevel >= _options.MinimumLogLevel;
+    }
+
+    public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception? exception, Func<TState, Exception?, string> formatter)
+    {
+        if (!IsEnabled(logLevel))
+        {
+            return;
+        }
+
+        // not quite ideal as this is a boxing allocation from Microsoft.Extensions.Logging.FormattedLogValues
+        /*
+        string? template = null;
+        object[]? parameters = null;
+        if (state is IReadOnlyList<KeyValuePair<string, object?>> formattedLogValues)
+        {
+            foreach (var formattedLogValue in formattedLogValues)
+            {
+                if (formattedLogValue.Key == "{OriginalFormat}" && formattedLogValue.Value is string formattedString)
+                {
+                    template = formattedString;
+                    break;
+                }
+            }
+        }
+        */
+
+        string message = formatter.Invoke(state, exception);
+
+        switch (logLevel)
+        {
+            case LogLevel.Trace:
+                _hub.Logger.LogTrace(message);
+                break;
+            case LogLevel.Debug:
+                _hub.Logger.LogDebug(message);
+                break;
+            case LogLevel.Information:
+                _hub.Logger.LogInfo(message);
+                break;
+            case LogLevel.Warning:
+                _hub.Logger.LogWarning(message);
+                break;
+            case LogLevel.Error:
+                _hub.Logger.LogError(message);
+                break;
+            case LogLevel.Critical:
+                _hub.Logger.LogFatal(message);
+                break;
+            case LogLevel.None:
+            default:
+                break;
+        }
+    }
+}
+
+file sealed class NullDisposable : IDisposable
+{
+    public static NullDisposable Instance { get; } = new NullDisposable();
+
+    private NullDisposable()
+    {
+    }
+
+    public void Dispose()
+    {
+    }
+}
diff --git a/src/Sentry.Extensions.Logging/SentryStructuredLoggerProvider.cs b/src/Sentry.Extensions.Logging/SentryStructuredLoggerProvider.cs
@@ -0,0 +1,32 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace Sentry.Extensions.Logging;
+
+/// <summary>
+/// Sentry Structured Logger Provider.
+/// </summary>
+[ProviderAlias("SentryLogs")]
+[Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+internal sealed class SentryStructuredLoggerProvider : ILoggerProvider
+{
+    private readonly IOptions<SentryLoggingOptions> _options;
+    private readonly IHub _hub;
+
+    // TODO: convert this comment into an automated test
+    // Constructor must be public for Microsoft.Extensions.DependencyInjection
+    public SentryStructuredLoggerProvider(IOptions<SentryLoggingOptions> options, IHub hub)
+    {
+        _options = options;
+        _hub = hub;
+    }
+
+    public ILogger CreateLogger(string categoryName)
+    {
+        return new SentryStructuredLogger(categoryName, _options.Value, _hub);
+    }
+
+    public void Dispose()
+    {
+    }
+}
diff --git a/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt b/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt
@@ -41,6 +41,8 @@ namespace Sentry.Extensions.Logging
         public bool InitializeSdk { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }
         public void ConfigureScope(System.Action<Sentry.Scope> action) { }
     }
     public static class SentryLoggingOptionsExtensions
diff --git a/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt b/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt
@@ -41,6 +41,8 @@ namespace Sentry.Extensions.Logging
         public bool InitializeSdk { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }
         public void ConfigureScope(System.Action<Sentry.Scope> action) { }
     }
     public static class SentryLoggingOptionsExtensions
diff --git a/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.Net4_8.verified.txt b/test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.Net4_8.verified.txt
@@ -41,6 +41,7 @@ namespace Sentry.Extensions.Logging
         public bool InitializeSdk { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }
+        public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }
         public void ConfigureScope(System.Action<Sentry.Scope> action) { }
     }
     public static class SentryLoggingOptionsExtensions
diff --git a/test/Sentry.Extensions.Logging.Tests/SentryLoggingOptionsSetupTests.cs b/test/Sentry.Extensions.Logging.Tests/SentryLoggingOptionsSetupTests.cs
@@ -25,6 +25,7 @@ public void Configure_BindsConfigurationToOptions()
             Distribution = "FakeDistribution",
             Environment = "Test",
             Dsn = "https://d4d82fc1c2c4032a83f3a29aa3a3aff@fake-sentry.io:65535/2147483647",
+            EnableLogs  = true,
             MaxQueueItems = 8,
             MaxCacheItems = 9,
             ShutdownTimeout = TimeSpan.FromSeconds(13),
@@ -55,6 +56,7 @@ public void Configure_BindsConfigurationToOptions()
 
             MinimumBreadcrumbLevel = LogLevel.Debug,
             MinimumEventLevel = LogLevel.Error,
+            MinimumLogLevel = LogLevel.None,
             InitializeSdk = true
         };
         var config = new ConfigurationBuilder()
@@ -74,6 +76,7 @@ public void Configure_BindsConfigurationToOptions()
                 ["Distribution"] = expected.Distribution,
                 ["Environment"] = expected.Environment,
                 ["Dsn"] = expected.Dsn,
+                ["EnableLogs"] = expected.EnableLogs.ToString(),
                 ["MaxQueueItems"] = expected.MaxQueueItems.ToString(),
                 ["MaxCacheItems"] = expected.MaxCacheItems.ToString(),
                 ["ShutdownTimeout"] = expected.ShutdownTimeout.ToString(),
@@ -105,6 +108,7 @@ public void Configure_BindsConfigurationToOptions()
                 ["JsonPreserveReferences"] = expected.JsonPreserveReferences.ToString(),
                 ["MinimumBreadcrumbLevel"] = expected.MinimumBreadcrumbLevel.ToString(),
                 ["MinimumEventLevel"] = expected.MinimumEventLevel.ToString(),
+                ["MinimumLogLevel"] = expected.MinimumLogLevel.ToString(),
                 ["InitializeSdk"] = expected.InitializeSdk.ToString(),
             })
             .Build();
@@ -134,6 +138,7 @@ public void Configure_BindsConfigurationToOptions()
             actual.Distribution.Should().Be(expected.Distribution);
             actual.Environment.Should().Be(expected.Environment);
             actual.Dsn.Should().Be(expected.Dsn);
+            actual.EnableLogs.Should().Be(expected.EnableLogs);
             actual.MaxQueueItems.Should().Be(expected.MaxQueueItems);
             actual.MaxCacheItems.Should().Be(expected.MaxCacheItems);
             actual.ShutdownTimeout.Should().Be(expected.ShutdownTimeout);
@@ -162,6 +167,7 @@ public void Configure_BindsConfigurationToOptions()
 
             actual.MinimumBreadcrumbLevel.Should().Be(expected.MinimumBreadcrumbLevel);
             actual.MinimumEventLevel.Should().Be(expected.MinimumEventLevel);
+            actual.MinimumLogLevel.Should().Be(expected.MinimumLogLevel);
             actual.InitializeSdk.Should().Be(expected.InitializeSdk);
         }
     }
diff --git a/test/Sentry.Extensions.Logging.Tests/SentryStructuredLoggerProviderTests.cs b/test/Sentry.Extensions.Logging.Tests/SentryStructuredLoggerProviderTests.cs
@@ -0,0 +1,25 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+
+namespace Sentry.Extensions.Logging.Tests;
+
+public class SentryStructuredLoggerProviderTests
+{
+    [Fact]
+    public void SmokeTest()
+    {
+        IOptions<SentryLoggingOptions> options = Options.Create(new SentryLoggingOptions
+        {
+            EnableLogs = true,
+        });
+        IHub hub = Substitute.For<IHub>();
+
+        var provider = new SentryStructuredLoggerProvider(options, hub);
+
+        ILogger logger = provider.CreateLogger("categoryName");
+
+        logger.Should().BeOfType<SentryStructuredLogger>();
+
+        provider.Dispose();
+    }
+}
diff --git a/test/Sentry.Extensions.Logging.Tests/SentryStructuredLoggerTests.cs b/test/Sentry.Extensions.Logging.Tests/SentryStructuredLoggerTests.cs
@@ -0,0 +1,38 @@
+#nullable enable
+
+using Microsoft.Extensions.Logging;
+
+namespace Sentry.Extensions.Logging.Tests;
+
+public class SentryStructuredLoggerTests
+{
+    [Fact]
+    public void SmokeTest()
+    {
+        string categoryName = "CategoryName";
+        SentryLoggingOptions options = new()
+        {
+            EnableLogs = true,
+        };
+        IHub hub = Substitute.For<IHub>();
+        hub.IsEnabled.Returns(true);
+        hub.Logger.Returns(Sentry.SentryStructuredLogger.CreateDisabled(hub));
+
+        var logger = new SentryStructuredLogger(categoryName, options, hub);
+
+        IDisposable? disposable = logger.BeginScope("state");
+        disposable.Should().NotBeNull();
+
+        logger.IsEnabled(LogLevel.Warning).Should().BeTrue();
+
+        EventId eventId = new(1, "eventId");
+        Exception exception = new InvalidOperationException();
+        Func<string, Exception?, string> formatter = (string state, Exception? exception) =>
+        {
+            state.Should().Be("state");
+            exception.Should().BeOfType<InvalidOperationException>();
+            return "Message";
+        };
+        logger.Log(LogLevel.Warning, eventId, "state", exception, formatter);
+    }
+}

Original file line number	Diff line number	Diff line change
`@@ -7,13 +7,16 @@ internal class BindableSentryLoggingOptions : BindableSentryOptions`
`7`	`7`	`{`
`8`	`8`	`public LogLevel? MinimumBreadcrumbLevel { get; set; }`
`9`	`9`	`public LogLevel? MinimumEventLevel { get; set; }`
	`10`	`+ [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]`
	`11`	`+ public LogLevel? MinimumLogLevel { get; set; }`
`10`	`12`	`public bool? InitializeSdk { get; set; }`
`11`	`13`
`12`	`14`	`public void ApplyTo(SentryLoggingOptions options)`
`13`	`15`	`{`
`14`	`16`	`base.ApplyTo(options);`
`15`	`17`	`options.MinimumBreadcrumbLevel = MinimumBreadcrumbLevel ?? options.MinimumBreadcrumbLevel;`
`16`	`18`	`options.MinimumEventLevel = MinimumEventLevel ?? options.MinimumEventLevel;`
	`19`	`+ options.MinimumLogLevel = MinimumLogLevel ?? options.MinimumLogLevel;`
`17`	`20`	`options.InitializeSdk = InitializeSdk ?? options.InitializeSdk;`
`18`	`21`	`}`
`19`	`22`	`}`
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,8 @@ namespace Sentry.Extensions.Logging`
`41`	`41`	`public bool InitializeSdk { get; set; }`
`42`	`42`	`public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }`
`43`	`43`	`public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }`
	`44`	`+ [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]`
	`45`	`+ public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }`
`44`	`46`	`public void ConfigureScope(System.Action<Sentry.Scope> action) { }`
`45`	`47`	`}`
`46`	`48`	`public static class SentryLoggingOptionsExtensions`
Original file line number	Diff line number	Diff line change
`@@ -41,6 +41,7 @@ namespace Sentry.Extensions.Logging`
`41`	`41`	`public bool InitializeSdk { get; set; }`
`42`	`42`	`public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }`
`43`	`43`	`public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }`
	`44`	`+ public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }`
`44`	`45`	`public void ConfigureScope(System.Action<Sentry.Scope> action) { }`
`45`	`46`	`}`
`46`	`47`	`public static class SentryLoggingOptionsExtensions`