feat: add Serilog integration (#4462)

Co-authored-by: Sentry Github Bot <[email protected]>
Co-authored-by: James Crosswell <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Features
+
+- Add (experimental) _Structured Logs_ integration for `Serilog` ([#4462](https://github.com/getsentry/sentry-dotnet/pull/4462))
+
 ### Fixes
 
 - Upload linked PDBs to fix non-IL-stripped symbolication for iOS ([#4527](https://github.com/getsentry/sentry-dotnet/pull/4527))

samples/Sentry.Samples.Serilog/Program.cs

@@ -25,6 +25,8 @@ private static void Main()
                 // Error and higher is sent as event (default is Error)
                 options.MinimumEventLevel = LogEventLevel.Error;
                 options.AttachStacktrace = true;
+                // send structured logs to Sentry
+                options.Experimental.EnableLogs = true;
                 // send PII like the username of the user logged in to the device
                 options.SendDefaultPii = true;
                 // Optional Serilog text formatter used to format LogEvent to string. If TextFormatter is set, FormatProvider is ignored.

src/Sentry.Serilog/LogLevelExtensions.cs

@@ -42,4 +42,18 @@ public static BreadcrumbLevel ToBreadcrumbLevel(this LogEventLevel level)
             _ => (BreadcrumbLevel)level
         };
     }
+
+    public static SentryLogLevel ToSentryLogLevel(this LogEventLevel level)
+    {
+        return level switch
+        {
+            LogEventLevel.Verbose => SentryLogLevel.Trace,
+            LogEventLevel.Debug => SentryLogLevel.Debug,
+            LogEventLevel.Information => SentryLogLevel.Info,
+            LogEventLevel.Warning => SentryLogLevel.Warning,
+            LogEventLevel.Error => SentryLogLevel.Error,
+            LogEventLevel.Fatal => SentryLogLevel.Fatal,
+            _ => (SentryLogLevel)level,
+        };
+    }
 }

src/Sentry.Serilog/SentrySink.Structured.cs

@@ -0,0 +1,126 @@
+using Sentry.Internal.Extensions;
+using Serilog.Parsing;
+
+namespace Sentry.Serilog;
+
+internal sealed partial class SentrySink
+{
+    private static void CaptureStructuredLog(IHub hub, SentryOptions options, LogEvent logEvent, string formatted, string? template)
+    {
+        GetTraceIdAndSpanId(hub, out var traceId, out var spanId);
+        GetStructuredLoggingParametersAndAttributes(logEvent, out var parameters, out var attributes);
+
+        SentryLog log = new(logEvent.Timestamp, traceId, logEvent.Level.ToSentryLogLevel(), formatted)
+        {
+            Template = template,
+            Parameters = parameters,
+            ParentSpanId = spanId,
+        };
+
+        log.SetDefaultAttributes(options, Sdk);
+
+        foreach (var attribute in attributes)
+        {
+            log.SetAttribute(attribute.Key, attribute.Value);
+        }
+
+        hub.Logger.CaptureLog(log);
+    }
+
+    private static void GetTraceIdAndSpanId(IHub hub, out SentryId traceId, out SpanId? spanId)
+    {
+        var span = hub.GetSpan();
+        if (span is not null)
+        {
+            traceId = span.TraceId;
+            spanId = span.SpanId;
+            return;
+        }
+
+        var scope = hub.GetScope();
+        if (scope is not null)
+        {
+            traceId = scope.PropagationContext.TraceId;
+            spanId = scope.PropagationContext.SpanId;
+            return;
+        }
+
+        traceId = SentryId.Empty;
+        spanId = null;
+    }
+
+    private static void GetStructuredLoggingParametersAndAttributes(LogEvent logEvent, out ImmutableArray<KeyValuePair<string, object>> parameters, out List<KeyValuePair<string, object>> attributes)
+    {
+        var propertyNames = new HashSet<string>();
+        foreach (var token in logEvent.MessageTemplate.Tokens)
+        {
+            if (token is PropertyToken property)
+            {
+                propertyNames.Add(property.PropertyName);
+            }
+        }
+
+        var @params = ImmutableArray.CreateBuilder<KeyValuePair<string, object>>();
+        attributes = new List<KeyValuePair<string, object>>();
+
+        foreach (var property in logEvent.Properties)
+        {
+            if (propertyNames.Contains(property.Key))
+            {
+                foreach (var parameter in GetLogEventProperties(property))
+                {
+                    @params.Add(parameter);
+                }
+            }
+            else
+            {
+                foreach (var attribute in GetLogEventProperties(property))
+                {
+                    attributes.Add(new KeyValuePair<string, object>($"property.{attribute.Key}", attribute.Value));
+                }
+            }
+        }
+
+        parameters = @params.DrainToImmutable();
+        return;
+
+        static IEnumerable<KeyValuePair<string, object>> GetLogEventProperties(KeyValuePair<string, LogEventPropertyValue> property)
+        {
+            if (property.Value is ScalarValue scalarValue)
+            {
+                if (scalarValue.Value is not null)
+                {
+                    yield return new KeyValuePair<string, object>(property.Key, scalarValue.Value);
+                }
+            }
+            else if (property.Value is SequenceValue sequenceValue)
+            {
+                if (sequenceValue.Elements.Count != 0)
+                {
+                    yield return new KeyValuePair<string, object>(property.Key, sequenceValue.ToString());
+                }
+            }
+            else if (property.Value is DictionaryValue dictionaryValue)
+            {
+                if (dictionaryValue.Elements.Count != 0)
+                {
+                    yield return new KeyValuePair<string, object>(property.Key, dictionaryValue.ToString());
+                }
+            }
+            else if (property.Value is StructureValue structureValue)
+            {
+                foreach (var prop in structureValue.Properties)
+                {
+                    if (LogEventProperty.IsValidName(prop.Name))
+                    {
+                        yield return new KeyValuePair<string, object>($"{property.Key}.{prop.Name}", prop.Value.ToString());
+                    }
+                }
+            }
+            else if (!property.Value.IsNull())
+            {
+                yield return new KeyValuePair<string, object>(property.Key, property.Value);
+            }
+        }
+    }
+}

src/Sentry.Serilog/SentrySink.cs

@@ -5,14 +5,20 @@ namespace Sentry.Serilog;
 /// </summary>
 /// <inheritdoc cref="IDisposable" />
 /// <inheritdoc cref="ILogEventSink" />
-internal sealed class SentrySink : ILogEventSink, IDisposable
+internal sealed partial class SentrySink : ILogEventSink, IDisposable
 {
     private readonly IDisposable? _sdkDisposable;
     private readonly SentrySerilogOptions _options;
 
     internal static readonly SdkVersion NameAndVersion
         = typeof(SentrySink).Assembly.GetNameAndVersion();
 
+    private static readonly SdkVersion Sdk = new()
+    {
+        Name = SdkName,
+        Version = NameAndVersion.Version,
+    };
+
     /// <summary>
     /// Serilog SDK name.
     /// </summary>
@@ -50,6 +56,11 @@ internal SentrySink(
 
     public void Emit(LogEvent logEvent)
     {
+        if (!IsEnabled(logEvent))
+        {
+            return;
+        }
+
         if (isReentrant.Value)
         {
             _options.DiagnosticLogger?.LogError($"Reentrant log event detected. Logging when inside the scope of another log event can cause a StackOverflowException. LogEventInfo.Message: {logEvent.MessageTemplate.Text}");
@@ -67,6 +78,15 @@ public void Emit(LogEvent logEvent)
         }
     }
 
+    private bool IsEnabled(LogEvent logEvent)
+    {
+        var options = _hubAccessor().GetSentryOptions();
+
+        return logEvent.Level >= _options.MinimumEventLevel
+            || logEvent.Level >= _options.MinimumBreadcrumbLevel
+            || options?.Experimental.EnableLogs is true;
+    }
+
     private void InnerEmit(LogEvent logEvent)
     {
         if (logEvent.TryGetSourceContext(out var context))
@@ -77,8 +97,7 @@ private void InnerEmit(LogEvent logEvent)
             }
         }
 
-        var hub = _hubAccessor();
-        if (hub is null || !hub.IsEnabled)
+        if (_hubAccessor() is not { IsEnabled: true } hub)
         {
             return;
         }
@@ -122,30 +141,37 @@ private void InnerEmit(LogEvent logEvent)
             }
         }
 
-        if (logEvent.Level < _options.MinimumBreadcrumbLevel)
+        if (logEvent.Level >= _options.MinimumBreadcrumbLevel)
         {
-            return;
+            Dictionary<string, string>? data = null;
+            if (exception != null && !string.IsNullOrWhiteSpace(formatted))
+            {
+                // Exception.Message won't be used as Breadcrumb message
+                // Avoid losing it by adding as data:
+                data = new Dictionary<string, string>
+                {
+                    { "exception_message", exception.Message }
+                };
+            }
+
+            hub.AddBreadcrumb(
+                _clock,
+                string.IsNullOrWhiteSpace(formatted)
+                    ? exception?.Message ?? ""
+                    : formatted,
+                context,
+                data: data,
+                level: logEvent.Level.ToBreadcrumbLevel());
         }
 
-        Dictionary<string, string>? data = null;
-        if (exception != null && !string.IsNullOrWhiteSpace(formatted))
+        // Read the options from the Hub, rather than the Sink's Serilog-Options, because 'EnableLogs' is declared in the base 'SentryOptions', rather than the derived 'SentrySerilogOptions'.
+        // In cases where Sentry's Serilog-Sink is added without a DSN (i.e., without initializing the SDK) and the SDK is initialized differently (e.g., through ASP.NET Core),
+        // then the 'EnableLogs' option of this Sink's Serilog-Options is default, but the Hub's Sentry-Options have the actual user-defined value configured.
+        var options = hub.GetSentryOptions();
+        if (options?.Experimental.EnableLogs is true)
         {
-            // Exception.Message won't be used as Breadcrumb message
-            // Avoid losing it by adding as data:
-            data = new Dictionary<string, string>
-            {
-                {"exception_message", exception.Message}
-            };
+            CaptureStructuredLog(hub, options, logEvent, formatted, template);
         }
-
-        hub.AddBreadcrumb(
-            _clock,
-            string.IsNullOrWhiteSpace(formatted)
-                ? exception?.Message ?? ""
-                : formatted,
-            context,
-            data: data,
-            level: logEvent.Level.ToBreadcrumbLevel());
     }
 
     private static bool IsSentryContext(string context) =>

src/Sentry.Serilog/SentrySinkExtensions.cs

@@ -13,8 +13,8 @@ public static class SentrySinkExtensions
     /// </summary>
     /// <param name="loggerConfiguration">The logger configuration .<seealso cref="LoggerSinkConfiguration"/></param>
     /// <param name="dsn">The Sentry DSN (required). <seealso cref="SentryOptions.Dsn"/></param>
-    /// <param name="minimumEventLevel">Minimum log level to send an event. <seealso cref="SentrySerilogOptions.MinimumEventLevel"/></param>
     /// <param name="minimumBreadcrumbLevel">Minimum log level to record a breadcrumb. <seealso cref="SentrySerilogOptions.MinimumBreadcrumbLevel"/></param>
+    /// <param name="minimumEventLevel">Minimum log level to send an event. <seealso cref="SentrySerilogOptions.MinimumEventLevel"/></param>
     /// <param name="formatProvider">The Serilog format provider. <seealso cref="IFormatProvider"/></param>
     /// <param name="textFormatter">The Serilog text formatter. <seealso cref="ITextFormatter"/></param>
     /// <param name="sendDefaultPii">Whether to include default Personal Identifiable information. <seealso cref="SentryOptions.SendDefaultPii"/></param>
@@ -35,6 +35,7 @@ public static class SentrySinkExtensions
     /// <param name="reportAssembliesMode">What mode to use for reporting referenced assemblies in each event sent to sentry. Defaults to <see cref="Sentry.ReportAssembliesMode.Version"/></param>
     /// <param name="deduplicateMode">What modes to use for event automatic de-duplication. <seealso cref="SentryOptions.DeduplicateMode"/></param>
     /// <param name="defaultTags">Default tags to add to all events. <seealso cref="SentryOptions.DefaultTags"/></param>
+    /// <param name="experimentalEnableLogs">Whether to send structured logs. <seealso cref="SentryOptions.SentryExperimentalOptions.EnableLogs"/></param>
     /// <returns><see cref="LoggerConfiguration"/></returns>
     /// <example>This sample shows how each item may be set from within a configuration file:
     /// <code>
@@ -50,7 +51,7 @@ public static class SentrySinkExtensions
     ///                     "dsn": "https://[email protected]",
     ///                     "minimumBreadcrumbLevel": "Verbose",
     ///                     "minimumEventLevel": "Error",
-    ///                     "outputTemplate": "{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}"///
+    ///                     "outputTemplate": "{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}",
     ///                     "sendDefaultPii": false,
     ///                     "isEnvironmentUser": false,
     ///                     "serverName": "MyServerName",
@@ -71,7 +72,8 @@ public static class SentrySinkExtensions
     ///                     "defaultTags": {
     ///                         "key-1", "value-1",
     ///                         "key-2", "value-2"
-    ///                     }
+    ///                     },
+    ///                     "experimentalEnableLogs": true
     ///                 }
     ///             }
     ///         ]
@@ -103,7 +105,8 @@ public static LoggerConfiguration Sentry(
         SentryLevel? diagnosticLevel = null,
         ReportAssembliesMode? reportAssembliesMode = null,
         DeduplicateMode? deduplicateMode = null,
-        Dictionary<string, string>? defaultTags = null)
+        Dictionary<string, string>? defaultTags = null,
+        bool? experimentalEnableLogs = null)
     {
         return loggerConfiguration.Sentry(o => ConfigureSentrySerilogOptions(o,
             dsn,
@@ -128,7 +131,8 @@ public static LoggerConfiguration Sentry(
             diagnosticLevel,
             reportAssembliesMode,
             deduplicateMode,
-            defaultTags));
+            defaultTags,
+            experimentalEnableLogs));
     }
 
     /// <summary>
@@ -157,7 +161,7 @@ public static LoggerConfiguration Sentry(
     ///                 "Args": {
     ///                     "minimumEventLevel": "Error",
     ///                     "minimumBreadcrumbLevel": "Verbose",
-    ///                     "outputTemplate": "{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}"///
+    ///                     "outputTemplate": "{Timestamp:o} [{Level:u3}] ({Application}/{MachineName}/{ThreadId}) {Message}{NewLine}{Exception}"
     ///                 }
     ///             }
     ///         ]
@@ -205,7 +209,8 @@ internal static void ConfigureSentrySerilogOptions(
         SentryLevel? diagnosticLevel = null,
         ReportAssembliesMode? reportAssembliesMode = null,
         DeduplicateMode? deduplicateMode = null,
-        Dictionary<string, string>? defaultTags = null)
+        Dictionary<string, string>? defaultTags = null,
+        bool? experimentalEnableLogs = null)
     {
         if (dsn is not null)
         {
@@ -317,6 +322,11 @@ internal static void ConfigureSentrySerilogOptions(
             sentrySerilogOptions.DeduplicateMode = deduplicateMode.Value;
         }
 
+        if (experimentalEnableLogs.HasValue)
+        {
+            sentrySerilogOptions.Experimental.EnableLogs = experimentalEnableLogs.Value;
+        }
+
         // Serilog-specific items
         sentrySerilogOptions.InitializeSdk = dsn is not null;  // Inferred from the Sentry overload that is used
         if (defaultTags?.Count > 0)
@@ -354,7 +364,6 @@ public static LoggerConfiguration Sentry(
             sdkDisposable = SentrySdk.Init(options);
         }
 
-        var minimumOverall = (LogEventLevel)Math.Min((int)options.MinimumBreadcrumbLevel, (int)options.MinimumEventLevel);
-        return loggerConfiguration.Sink(new SentrySink(options, sdkDisposable), minimumOverall);
+        return loggerConfiguration.Sink(new SentrySink(options, sdkDisposable));
     }
 }

src/Sentry/SentryLog.cs

@@ -9,6 +9,7 @@ namespace Sentry;
 /// <para>This API is experimental and it may change in the future.</para>
 /// </summary>
 [Experimental(DiagnosticId.ExperimentalFeature)]
+[DebuggerDisplay(@"SentryLog \{ Level = {Level}, Message = '{Message}' \}")]
 public sealed class SentryLog
 {
     private readonly Dictionary<string, SentryAttribute> _attributes;

test/Sentry.Serilog.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt

@@ -46,6 +46,7 @@ namespace Serilog
                     Sentry.SentryLevel? diagnosticLevel = default,
                     Sentry.ReportAssembliesMode? reportAssembliesMode = default,
                     Sentry.DeduplicateMode? deduplicateMode = default,
-                    System.Collections.Generic.Dictionary<string, string>? defaultTags = null) { }
+                    System.Collections.Generic.Dictionary<string, string>? defaultTags = null,
+                    bool? experimentalEnableLogs = default) { }
     }
 }