WIP: Logs for Sentry.Extensions.Logging and integrations for Sentry.AspNetCore and Sentry.Maui

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Features
+
+- Add experimental support for [Sentry Structured Logging](https://docs.sentry.io/product/explore/logs/) via `SentrySdk.Experimental.Logger` ([#4158](https://github.com/getsentry/sentry-dotnet/pull/4158))
+- Add experimental integrations of [Sentry Structured Logging](https://docs.sentry.io/product/explore/logs/) ([#4193](https://github.com/getsentry/sentry-dotnet/pull/4193))
+    - `Sentry.AspNetCore`, enabled via `SentryAspNetCoreOptions.Experimental.EnableLogs`
+    - `Sentry.Extensions.Logging`, enabled via `SentryLoggingOptions.Experimental.EnableLogs`
+    - `Sentry.Maui`, enabled via `SentryMauiOptions.Experimental.EnableLogs`
 ### Fixes
 
 - Native AOT: don't load SentryNative on unsupported platforms ([#4347](https://github.com/getsentry/sentry-dotnet/pull/4347))

samples/Sentry.Samples.AspNetCore.Basic/Program.cs

@@ -15,6 +15,9 @@
     // Log debug information about the Sentry SDK
     options.Debug = true;
 #endif
+
+    // This option enables Logs sent to Sentry.
+    options.Experimental.EnableLogs = true;
 });
 
 var app = builder.Build();

samples/Sentry.Samples.ME.Logging/Program.cs

@@ -23,7 +23,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.ExperimentalLogging.MinimumLogLevel = LogLevel.Trace; // This level or above will result in log sent to Sentry
 
+        // This option enables Logs sent to Sentry.
+        options.Experimental.EnableLogs = true;
+        options.Experimental.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);
 

samples/Sentry.Samples.Maui/MauiProgram.cs

@@ -33,6 +33,7 @@ public static MauiApp CreateMauiApp()
                 options.AttachScreenshot = true;
 
                 options.Debug = true;
+                options.Experimental.EnableLogs = true;
                 options.SampleRate = 1.0F;
 
                 // The Sentry MVVM Community Toolkit integration automatically creates traces for async relay commands,

src/Sentry.AspNetCore/SentryAspNetCoreStructuredLoggerProvider.cs

@@ -0,0 +1,18 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Sentry.Extensions.Logging;
+
+namespace Sentry.AspNetCore;
+
+/// <summary>
+/// Structured Logger Provider for Sentry.
+/// </summary>
+[ProviderAlias("SentryLogs")]
+[Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+internal sealed class SentryAspNetCoreStructuredLoggerProvider : SentryStructuredLoggerProvider
+{
+    public SentryAspNetCoreStructuredLoggerProvider(IOptions<SentryAspNetCoreOptions> options, IHub hub)
+        : base(options, hub)
+    {
+    }
+}

src/Sentry.AspNetCore/SentryWebHostBuilderExtensions.cs

@@ -93,10 +93,16 @@ public static IWebHostBuilder UseSentry(
             _ = logging.Services
                 .AddSingleton<IConfigureOptions<SentryAspNetCoreOptions>, SentryAspNetCoreOptionsSetup>();
             _ = logging.Services.AddSingleton<ILoggerProvider, SentryAspNetCoreLoggerProvider>();
+            _ = logging.Services.AddSingleton<ILoggerProvider, SentryAspNetCoreStructuredLoggerProvider>();
 
             _ = logging.AddFilter<SentryAspNetCoreLoggerProvider>(
                 "Microsoft.AspNetCore.Diagnostics.ExceptionHandlerMiddleware",
                 LogLevel.None);
+            _ = logging.AddFilter<SentryAspNetCoreStructuredLoggerProvider>(static (string? categoryName, LogLevel logLevel) =>
+            {
+                return categoryName is null
+                    || (categoryName != "Sentry.ISentryClient" && categoryName != "Sentry.AspNetCore.SentryMiddleware");
+            });
 
             var sentryBuilder = logging.Services.AddSentry();
             configureSentry?.Invoke(context, sentryBuilder);

src/Sentry.Extensions.Logging/BindableSentryLoggingOptions.cs

@@ -9,11 +9,22 @@ internal class BindableSentryLoggingOptions : BindableSentryOptions
     public LogLevel? MinimumEventLevel { get; set; }
     public bool? InitializeSdk { get; set; }
 
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public BindableSentryLoggingExperimentalOptions ExperimentalLogging { get; set; } = new();
+
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    internal sealed class BindableSentryLoggingExperimentalOptions
+    {
+        public LogLevel? MinimumLogLevel { get; set; }
+    }
+
     public void ApplyTo(SentryLoggingOptions options)
     {
         base.ApplyTo(options);
         options.MinimumBreadcrumbLevel = MinimumBreadcrumbLevel ?? options.MinimumBreadcrumbLevel;
         options.MinimumEventLevel = MinimumEventLevel ?? options.MinimumEventLevel;
         options.InitializeSdk = InitializeSdk ?? options.InitializeSdk;
+
+        options.ExperimentalLogging.MinimumLogLevel = ExperimentalLogging.MinimumLogLevel ?? options.ExperimentalLogging.MinimumLogLevel;
     }
 }

src/Sentry.Extensions.Logging/LoggingBuilderExtensions.cs

@@ -51,13 +51,22 @@ 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 != "Sentry.ISentryClient";
+        });
+
         return builder;
     }
 }

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,7 +23,7 @@ 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.
@@ -48,4 +50,39 @@ public class SentryLoggingOptions : SentryOptions
     /// List of callbacks to be invoked when initializing the SDK
     /// </summary>
     internal Action<Scope>[] ConfigureScopeCallbacks { get; set; } = Array.Empty<Action<Scope>>();
+
+    /// <summary>
+    /// Experimental Sentry Logging features.
+    /// </summary>
+    /// <remarks>
+    /// This and related experimental APIs may change in the future.
+    /// </remarks>
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public SentryLoggingExperimentalOptions ExperimentalLogging { get; set; } = new();
+
+    /// <summary>
+    /// Experimental Sentry Logging options.
+    /// </summary>
+    /// <remarks>
+    /// This and related experimental APIs may change in the future.
+    /// </remarks>
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public sealed class SentryLoggingExperimentalOptions
+    {
+        internal SentryLoggingExperimentalOptions()
+        {
+        }
+
+        /// <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>
+        public LogLevel MinimumLogLevel { get; set; } = LogLevel.Trace;
+    }
 }

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.Experimental.EnableLogs
+            && logLevel != LogLevel.None
+            && logLevel >= _options.ExperimentalLogging.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()
+    {
+    }
+}

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 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()
+    {
+    }
+}

src/Sentry.Maui/Internal/SentryMauiStructuredLoggerProvider.cs

@@ -0,0 +1,15 @@
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Sentry.Extensions.Logging;
+
+namespace Sentry.Maui.Internal;
+
+[ProviderAlias("SentryLogs")]
+[Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+internal sealed class SentryMauiStructuredLoggerProvider : SentryStructuredLoggerProvider
+{
+    public SentryMauiStructuredLoggerProvider(IOptions<SentryMauiOptions> options, IHub hub)
+        : base(options, hub)
+    {
+    }
+}

src/Sentry.Maui/SentryMauiAppBuilderExtensions.cs

@@ -52,10 +52,17 @@ public static MauiAppBuilder UseSentry(this MauiAppBuilder builder,
 
         services.AddLogging();
         services.AddSingleton<ILoggerProvider, SentryMauiLoggerProvider>();
+        services.AddSingleton<ILoggerProvider, SentryMauiStructuredLoggerProvider>();
         services.AddSingleton<IMauiInitializeService, SentryMauiInitializer>();
         services.AddSingleton<IConfigureOptions<SentryMauiOptions>, SentryMauiOptionsSetup>();
         services.AddSingleton<Disposer>();
 
+        builder.Logging.AddFilter<SentryMauiStructuredLoggerProvider>(static (string? categoryName, LogLevel logLevel) =>
+        {
+            return categoryName is null
+                || categoryName != "Sentry.ISentryClient";
+        });
+
         // Resolve the configured options and register any element event binders from these
         var options = new SentryMauiOptions();
         configureOptions?.Invoke(options);

test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt

@@ -38,10 +38,17 @@ namespace Sentry.Extensions.Logging
     public class SentryLoggingOptions : Sentry.SentryOptions
     {
         public SentryLoggingOptions() { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public Sentry.Extensions.Logging.SentryLoggingOptions.SentryLoggingExperimentalOptions ExperimentalLogging { get; set; }
         public bool InitializeSdk { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }
         public void ConfigureScope(System.Action<Sentry.Scope> action) { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public sealed class SentryLoggingExperimentalOptions
+        {
+            public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }
+        }
     }
     public static class SentryLoggingOptionsExtensions
     {

test/Sentry.Extensions.Logging.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt

@@ -38,10 +38,17 @@ namespace Sentry.Extensions.Logging
     public class SentryLoggingOptions : Sentry.SentryOptions
     {
         public SentryLoggingOptions() { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public Sentry.Extensions.Logging.SentryLoggingOptions.SentryLoggingExperimentalOptions ExperimentalLogging { get; set; }
         public bool InitializeSdk { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumBreadcrumbLevel { get; set; }
         public Microsoft.Extensions.Logging.LogLevel MinimumEventLevel { get; set; }
         public void ConfigureScope(System.Action<Sentry.Scope> action) { }
+        [System.Diagnostics.CodeAnalysis.Experimental("SENTRY0001")]
+        public sealed class SentryLoggingExperimentalOptions
+        {
+            public Microsoft.Extensions.Logging.LogLevel MinimumLogLevel { get; set; }
+        }
     }
     public static class SentryLoggingOptionsExtensions
     {