WIP: Logs pre-release

.github/workflows/device-tests-ios.yml

@@ -11,6 +11,7 @@ on:
 
 jobs:
   ios-tests:
+    if: false
     runs-on: macos-15
     env:
       DOTNET_CLI_TELEMETRY_OPTOUT: 1

CHANGELOG.md

@@ -1,13 +1,21 @@
 # Changelog
 
-## Unreleased
+## 5.12.0-alpha.0
 
+### 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`
 ### API changes
 
 - App Hang Tracking for iOS is now disabled by default, until this functionality is more stable. If you want to use it in your applications then you'll need to enable this manually. ([#4320](https://github.com/getsentry/sentry-dotnet/pull/4320))
 
 ### 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))
 - Added StartSpan and GetTransaction methods to the SentrySdk ([#4303](https://github.com/getsentry/sentry-dotnet/pull/4303))
 
 ### Fixes

Directory.Build.props

@@ -1,7 +1,7 @@
 <Project>
 
   <PropertyGroup>
-    <VersionPrefix>5.11.2</VersionPrefix>
+    <VersionPrefix>5.12.0-alpha.0</VersionPrefix>
     <LangVersion>13</LangVersion>
     <AccelerateBuildsInVisualStudio>true</AccelerateBuildsInVisualStudio>
     <TreatWarningsAsErrors>true</TreatWarningsAsErrors>

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.Console.Basic/Program.cs

@@ -3,6 +3,7 @@
  * - Error Monitoring (both handled and unhandled exceptions)
  * - Performance Tracing (Transactions / Spans)
  * - Release Health (Sessions)
+ * - Logs
  * - MSBuild integration for Source Context (see the csproj)
  *
  * For more advanced features of the SDK, see Sentry.Samples.Console.Customized.
@@ -35,6 +36,20 @@
 
     // This option tells Sentry to capture 100% of traces. You still need to start transactions and spans.
     options.TracesSampleRate = 1.0;
+
+    // This option enables Sentry Logs created via SentrySdk.Logger.
+    options.Experimental.EnableLogs = true;
+    options.Experimental.SetBeforeSendLog(static log =>
+    {
+        // A demonstration of how you can drop logs based on some attribute they have
+        if (log.TryGetAttribute("suppress", out var attribute) && attribute is true)
+        {
+            return null;
+        }
+
+        // Drop logs with level Info
+        return log.Level is SentryLogLevel.Info ? null : log;
+    });
 });
 
 // This starts a new transaction and attaches it to the scope.
@@ -58,6 +73,7 @@ async Task FirstFunction()
     var httpClient = new HttpClient(messageHandler, true);
     var html = await httpClient.GetStringAsync("https://example.com/");
     WriteLine(html);
+    SentrySdk.Experimental.Logger.LogInfo("HTTP Request completed.");
 }
 
 async Task SecondFunction()
@@ -77,6 +93,8 @@ async Task SecondFunction()
         // This is an example of capturing a handled exception.
         SentrySdk.CaptureException(exception);
         span.Finish(exception);
+
+        SentrySdk.Experimental.Logger.LogError("Error with message: {0}", [exception.Message], static log => log.SetAttribute("method", nameof(SecondFunction)));
     }
 
     span.Finish();
@@ -90,6 +108,8 @@ async Task ThirdFunction()
         // Simulate doing some work
         await Task.Delay(100);
 
+        SentrySdk.Experimental.Logger.LogFatal("Crash imminent!", [], static log => log.SetAttribute("suppress", true));
+
         // This is an example of an unhandled exception.  It will be captured automatically.
         throw new InvalidOperationException("Something happened that crashed the app!");
     }

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