feat(logs): initial API for Sentry Logs

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add experimental support for _Sentry Structured Logging_ via `SentrySdk.Logger` ([#4158](https://github.com/getsentry/sentry-dotnet/pull/4158))
 ## 5.8.0
 
 ### Features

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

@@ -33,6 +33,19 @@
 
     // This option tells Sentry to capture 100% of traces. You still need to start transactions and spans.
     options.TracesSampleRate = 1.0;
+
+    // This option enables the (experimental) Sentry Logs.
+    options.EnableLogs = true;
+    options.SetBeforeSendLog(static log =>
+    {
+        if (log.TryGetAttribute("suppress", out bool attribute) && attribute)
+        {
+            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.
@@ -56,6 +69,7 @@ async Task FirstFunction()
     var httpClient = new HttpClient(messageHandler, true);
     var html = await httpClient.GetStringAsync("https://example.com/");
     WriteLine(html);
+    SentrySdk.Logger.LogInfo("HTTP Request completed.");
 }
 
 async Task SecondFunction()
@@ -75,6 +89,8 @@ async Task SecondFunction()
         // This is an example of capturing a handled exception.
         SentrySdk.CaptureException(exception);
         span.Finish(exception);
+
+        SentrySdk.Logger.LogError("Error with message: {0}", [exception.Message], static log => log.SetAttribute("method", nameof(SecondFunction)));
     }
 
     span.Finish();
@@ -88,6 +104,8 @@ async Task ThirdFunction()
         // Simulate doing some work
         await Task.Delay(100);
 
+        SentrySdk.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!");
     }

src/Sentry/BindableSentryOptions.cs

@@ -20,6 +20,8 @@ internal partial class BindableSentryOptions
     public string? Distribution { get; set; }
     public string? Environment { get; set; }
     public string? Dsn { get; set; }
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public bool? EnableLogs { get; set; }
     public int? MaxQueueItems { get; set; }
     public int? MaxCacheItems { get; set; }
     public TimeSpan? ShutdownTimeout { get; set; }
@@ -68,6 +70,7 @@ public void ApplyTo(SentryOptions options)
         options.Distribution = Distribution ?? options.Distribution;
         options.Environment = Environment ?? options.Environment;
         options.Dsn = Dsn ?? options.Dsn;
+        options.EnableLogs = EnableLogs ?? options.EnableLogs;
         options.MaxQueueItems = MaxQueueItems ?? options.MaxQueueItems;
         options.MaxCacheItems = MaxCacheItems ?? options.MaxCacheItems;
         options.ShutdownTimeout = ShutdownTimeout ?? options.ShutdownTimeout;

src/Sentry/Extensibility/DiagnosticLoggerExtensions.cs

@@ -58,6 +58,17 @@ internal static void LogDebug<TArg, TArg2>(
         TArg2 arg2)
         => options.DiagnosticLogger?.LogIfEnabled(SentryLevel.Debug, null, message, arg, arg2);
 
+    /// <summary>
+    /// Log a debug message.
+    /// </summary>
+    public static void LogDebug<TArg, TArg2, TArg3>(
+        this IDiagnosticLogger logger,
+        string message,
+        TArg arg,
+        TArg2 arg2,
+        TArg3 arg3)
+        => logger.LogIfEnabled(SentryLevel.Debug, null, message, arg, arg2, arg3);
+
     /// <summary>
     /// Log a debug message.
     /// </summary>
@@ -233,6 +244,17 @@ internal static void LogWarning<TArg, TArg2>(
         TArg2 arg2)
         => options.DiagnosticLogger?.LogIfEnabled(SentryLevel.Warning, null, message, arg, arg2);
 
+    /// <summary>
+    /// Log a warning message.
+    /// </summary>
+    public static void LogWarning<TArg, TArg2, TArg3>(
+        this IDiagnosticLogger logger,
+        string message,
+        TArg arg,
+        TArg2 arg2,
+        TArg3 arg3)
+        => logger.LogIfEnabled(SentryLevel.Warning, null, message, arg, arg2, arg3);
+
     /// <summary>
     /// Log a warning message.
     /// </summary>

src/Sentry/Extensibility/DisabledHub.cs

@@ -21,6 +21,7 @@ public class DisabledHub : IHub, IDisposable
 
     private DisabledHub()
     {
+        Logger = SentryStructuredLogger.CreateDisabled(this);
     }
 
     /// <summary>
@@ -228,4 +229,11 @@ public void CaptureUserFeedback(UserFeedback userFeedback)
     /// No-Op.
     /// </summary>
     public SentryId LastEventId => SentryId.Empty;
+
+    /// <summary>
+    /// Disabled Logger.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public SentryStructuredLogger Logger { get; }
 }

src/Sentry/Extensibility/HubAdapter.cs

@@ -32,6 +32,13 @@ private HubAdapter() { }
     /// </summary>
     public SentryId LastEventId { [DebuggerStepThrough] get => SentrySdk.LastEventId; }
 
+    /// <summary>
+    /// Forwards the call to <see cref="SentrySdk"/>.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public SentryStructuredLogger Logger { [DebuggerStepThrough] get => SentrySdk.Logger; }
+
     /// <summary>
     /// Forwards the call to <see cref="SentrySdk"/>.
     /// </summary>

src/Sentry/IHub.cs

@@ -17,6 +17,20 @@ public interface IHub : ISentryClient, ISentryScopeManager
     /// </summary>
     public SentryId LastEventId { get; }
 
+    /// <summary>
+    /// Creates and sends logs to Sentry.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <remarks>
+    /// Available options:
+    /// <list type="bullet">
+    /// <item><see cref="Sentry.SentryOptions.EnableLogs"/></item>
+    /// <item><see cref="Sentry.SentryOptions.SetBeforeSendLog(System.Func{SentryLog, SentryLog})"/></item>
+    /// </list>
+    /// </remarks>
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    public SentryStructuredLogger Logger { get; }
+
     /// <summary>
     /// Starts a transaction.
     /// </summary>

src/Sentry/Infrastructure/DiagnosticId.cs

@@ -2,10 +2,8 @@ namespace Sentry.Infrastructure;
 
 internal static class DiagnosticId
 {
-#if NET5_0_OR_GREATER
     /// <summary>
     /// Indicates that the feature is experimental and may be subject to change or removal in future versions.
     /// </summary>
     internal const string ExperimentalFeature = "SENTRY0001";
-#endif
 }

src/Sentry/Internal/Hub.cs

@@ -66,6 +66,8 @@ internal Hub(
             PushScope();
         }
 
+        Logger = new SentryStructuredLogger(this, ScopeManager, options, _clock);
+
 #if MEMORY_DUMP_SUPPORTED
         if (options.HeapDumpOptions is not null)
         {
@@ -745,4 +747,7 @@ public void Dispose()
     }
 
     public SentryId LastEventId => CurrentScope.LastEventId;
+
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public SentryStructuredLogger Logger { get; }
 }

src/Sentry/Protocol/Envelopes/Envelope.cs

@@ -445,6 +445,22 @@ internal static Envelope FromClientReport(ClientReport clientReport)
         return new Envelope(header, items);
     }
 
+    // TODO: This is temporary. We don't expect single log messages to become an envelope by themselves since batching is needed
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    internal static Envelope FromLog(SentryLog log)
+    {
+        //TODO: allow batching Sentry logs
+        //see https://github.com/getsentry/sentry-dotnet/issues/4132
+        var header = DefaultHeader;
+
+        var items = new[]
+        {
+            EnvelopeItem.FromLog(log)
+        };
+
+        return new Envelope(header, items);
+    }
+
     private static async Task<IReadOnlyDictionary<string, object?>> DeserializeHeaderAsync(
         Stream stream,
         CancellationToken cancellationToken = default)

src/Sentry/Protocol/Envelopes/EnvelopeItem.cs

@@ -24,6 +24,7 @@ public sealed class EnvelopeItem : ISerializable, IDisposable
     internal const string TypeValueProfile = "profile";
     internal const string TypeValueMetric = "statsd";
     internal const string TypeValueCodeLocations = "metric_meta";
+    internal const string TypeValueLog = "log";
 
     private const string LengthKey = "length";
     private const string FileNameKey = "filename";
@@ -370,6 +371,21 @@ internal static EnvelopeItem FromClientReport(ClientReport report)
         return new EnvelopeItem(header, new JsonSerializable(report));
     }
 
+    [Experimental(Infrastructure.DiagnosticId.ExperimentalFeature)]
+    internal static EnvelopeItem FromLog(SentryLog log)
+    {
+        //TODO: allow batching Sentry logs
+        //see https://github.com/getsentry/sentry-dotnet/issues/4132
+        var header = new Dictionary<string, object?>(3, StringComparer.Ordinal)
+        {
+            [TypeKey] = TypeValueLog,
+            ["item_count"] = 1,
+            ["content_type"] = "application/vnd.sentry.items.log+json",
+        };
+
+        return new EnvelopeItem(header, new JsonSerializable(log));
+    }
+
     private static async Task<Dictionary<string, object?>> DeserializeHeaderAsync(
         Stream stream,
         CancellationToken cancellationToken = default)

src/Sentry/Protocol/SentryAttribute.cs

@@ -0,0 +1,107 @@
+namespace Sentry.Protocol;
+
+[DebuggerDisplay(@"\{ Value = {Value}, Type = {Type} \}")]
+internal readonly struct SentryAttribute
+{
+    public SentryAttribute(object value, string type)
+    {
+        Value = value;
+        Type = type;
+    }
+
+    public object Value { get; }
+    public string Type { get; }
+}
+
+internal static class SentryAttributeSerializer
+{
+    internal static void WriteAttribute(Utf8JsonWriter writer, string propertyName, SentryAttribute attribute)
+    {
+        Debug.Assert(attribute.Type is not null);
+        writer.WritePropertyName(propertyName);
+        WriteAttributeValue(writer, attribute.Value, attribute.Type);
+    }
+
+    internal static void WriteAttribute(Utf8JsonWriter writer, string propertyName, object value, string type)
+    {
+        writer.WritePropertyName(propertyName);
+        WriteAttributeValue(writer, value, type);
+    }
+
+    internal static void WriteAttribute(Utf8JsonWriter writer, string propertyName, object value)
+    {
+        writer.WritePropertyName(propertyName);
+        WriteAttributeValue(writer, value);
+    }
+
+    private static void WriteAttributeValue(Utf8JsonWriter writer, object value, string type)
+    {
+        writer.WriteStartObject();
+
+        if (type == "string")
+        {
+            writer.WriteString("value", (string)value);
+            writer.WriteString("type", type);
+        }
+        else if (type == "boolean")
+        {
+            writer.WriteBoolean("value", (bool)value);
+            writer.WriteString("type", type);
+        }
+        else if (type == "integer")
+        {
+            writer.WriteNumber("value", (long)value);
+            writer.WriteString("type", type);
+        }
+        else if (type == "double")
+        {
+            writer.WriteNumber("value", (double)value);
+            writer.WriteString("type", type);
+        }
+        else
+        {
+            writer.WriteString("value", value.ToString());
+            writer.WriteString("type", "string");
+        }
+
+        writer.WriteEndObject();
+    }
+
+    private static void WriteAttributeValue(Utf8JsonWriter writer, object value)
+    {
+        writer.WriteStartObject();
+
+        if (value is string str)
+        {
+            writer.WriteString("value", str);
+            writer.WriteString("type", "string");
+        }
+        else if (value is bool boolean)
+        {
+            writer.WriteBoolean("value", boolean);
+            writer.WriteString("type", "boolean");
+        }
+        else if (value is int int32)
+        {
+            writer.WriteNumber("value", int32);
+            writer.WriteString("type", "integer");
+        }
+        else if (value is long int64)
+        {
+            writer.WriteNumber("value", int64);
+            writer.WriteString("type", "integer");
+        }
+        else if (value is double float64)
+        {
+            writer.WriteNumber("value", float64);
+            writer.WriteString("type", "double");
+        }
+        else
+        {
+            writer.WriteString("value", value.ToString());
+            writer.WriteString("type", "string");
+        }
+
+        writer.WriteEndObject();
+    }
+}