ref(logs): allow out-of-range Log-Level

Author: Flash0ver

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/SentryLog.cs

@@ -13,7 +13,6 @@ namespace Sentry;
 public sealed class SentryLog : ISentryJsonSerializable
 {
     private readonly Dictionary<string, SentryAttribute> _attributes;
-    private readonly SentryLogLevel _level;
 
     [SetsRequiredMembers]
     internal SentryLog(DateTimeOffset timestamp, SentryId traceId, SentryLogLevel level, string message)
@@ -47,15 +46,7 @@ internal SentryLog(DateTimeOffset timestamp, SentryId traceId, SentryLogLevel le
     /// <para>This API is experimental and it may change in the future.</para>
     /// </summary>
     [Experimental(DiagnosticId.ExperimentalFeature)]
-    public required SentryLogLevel Level
-    {
-        get => _level;
-        init
-        {
-            SentryLogLevelExtensions.ThrowIfOutOfRange(value);
-            _level = value;
-        }
-    }
+    public required SentryLogLevel Level { get; init; }
 
     /// <summary>
     /// The formatted log message.
@@ -236,7 +227,7 @@ public void WriteTo(Utf8JsonWriter writer, IDiagnosticLogger? logger)
 
         writer.WriteNumber("timestamp", Timestamp.ToUnixTimeSeconds());
 
-        var (severityText, severityNumber) = Level.ToSeverityTextAndOptionalSeverityNumber();
+        var (severityText, severityNumber) = Level.ToSeverityTextAndOptionalSeverityNumber(logger);
         writer.WriteString("level", severityText);
 
         writer.WriteString("body", Message);

src/Sentry/SentryLogLevel.cs

@@ -1,3 +1,4 @@
+using Sentry.Extensibility;
 using Sentry.Infrastructure;
 
 namespace Sentry;
@@ -39,10 +40,11 @@ public enum SentryLogLevel
 [Experimental(DiagnosticId.ExperimentalFeature)]
 internal static class SentryLogLevelExtensions
 {
-    internal static (string, int?) ToSeverityTextAndOptionalSeverityNumber(this SentryLogLevel level)
+    internal static (string, int?) ToSeverityTextAndOptionalSeverityNumber(this SentryLogLevel level, IDiagnosticLogger? logger)
     {
         return (int)level switch
         {
+            <= 0 => Underflow(level, logger),
             1 => ("trace", null),
             >= 2 and <= 4 => ("trace", (int)level),
             5 => ("debug", null),
@@ -55,27 +57,19 @@ internal static (string, int?) ToSeverityTextAndOptionalSeverityNumber(this Sent
             >= 18 and <= 20 => ("error", (int)level),
             21 => ("fatal", null),
             >= 22 and <= 24 => ("fatal", (int)level),
-            _ => ThrowOutOfRange<(string, int?)>(level, nameof(level)),
+            >= 25 => Overflow(level, logger),
         };
     }
 
-    internal static void ThrowIfOutOfRange(SentryLogLevel level, [CallerArgumentExpression(nameof(level))] string? paramName = null)
+    private static (string, int?) Underflow(SentryLogLevel level, IDiagnosticLogger? logger)
     {
-        if ((int)level is < 1 or > 24)
-        {
-            ThrowOutOfRange(level, paramName);
-        }
-    }
-
-    [DoesNotReturn]
-    private static void ThrowOutOfRange(SentryLogLevel level, string? paramName)
-    {
-        throw new ArgumentOutOfRangeException(paramName, level, "Severity must be between 1 (inclusive) and 24 (inclusive).");
+        logger?.LogDebug("Log level {0} out of range ... clamping to minimum value {1} ({2})", level, 1, "trace");
+        return ("trace", 1);
     }
 
-    [DoesNotReturn]
-    private static T ThrowOutOfRange<T>(SentryLogLevel level, string? paramName)
+    private static (string, int?) Overflow(SentryLogLevel level, IDiagnosticLogger? logger)
     {
-        throw new ArgumentOutOfRangeException(paramName, level, "Severity must be between 1 (inclusive) and 24 (inclusive).");
+        logger?.LogDebug("Log level {0} out of range ... clamping to maximum value {1} ({2})", level, 24, "fatal");
+        return ("fatal", 24);
     }
 }

test/Sentry.Tests/SentryLogLevelTests.cs

@@ -5,57 +5,45 @@ namespace Sentry.Tests;
 /// </summary>
 public class SentryLogLevelTests
 {
+    private readonly InMemoryDiagnosticLogger _logger;
+
+    public SentryLogLevelTests()
+    {
+        _logger = new InMemoryDiagnosticLogger();
+    }
+
     [Theory]
     [MemberData(nameof(SeverityTextAndSeverityNumber))]
     public void SeverityTextAndSeverityNumber_WithinRange_MatchesProtocol(int level, string text, int? number)
     {
         var @enum = (SentryLogLevel)level;
 
-        var (severityText, severityNumber) = @enum.ToSeverityTextAndOptionalSeverityNumber();
+        var (severityText, severityNumber) = @enum.ToSeverityTextAndOptionalSeverityNumber(_logger);
 
         Assert.Multiple(
             () => Assert.Equal(text, severityText),
             () => Assert.Equal(number, severityNumber));
+        Assert.Empty(_logger.Entries);
     }
 
     [Theory]
-    [InlineData(0)]
-    [InlineData(25)]
-    public void SeverityTextAndSeverityNumber_OutOfRange_ThrowOutOfRange(int level)
+    [InlineData(0, "trace", 1, "minimum")]
+    [InlineData(25, "fatal", 24, "maximum")]
+    public void SeverityTextAndSeverityNumber_OutOfRange_ClampValue(int level, string text, int? number, string clamp)
     {
         var @enum = (SentryLogLevel)level;
 
-        var exception = Assert.Throws<ArgumentOutOfRangeException>("level", () => @enum.ToSeverityTextAndOptionalSeverityNumber());
-        Assert.StartsWith("Severity must be between 1 (inclusive) and 24 (inclusive).", exception.Message);
-        Assert.Equal(level, (int)exception.ActualValue!);
-    }
-
-    [Fact]
-    public void ThrowOutOfRange_WithinRange_DoesNotThrow()
-    {
-        var range = Enumerable.Range(1, 24);
+        var (severityText, severityNumber) = @enum.ToSeverityTextAndOptionalSeverityNumber(_logger);
 
-        var count = 0;
-        foreach (var item in range)
-        {
-            var level = (SentryLogLevel)item;
-            SentryLogLevelExtensions.ThrowIfOutOfRange(level);
-            count++;
-        }
-
-        Assert.Equal(24, count);
-    }
-
-    [Theory]
-    [InlineData(0)]
-    [InlineData(25)]
-    public void ThrowOutOfRange_OutOfRange_Throws(int level)
-    {
-        var @enum = (SentryLogLevel)level;
-
-        var exception = Assert.Throws<ArgumentOutOfRangeException>("@enum", () => SentryLogLevelExtensions.ThrowIfOutOfRange(@enum));
-        Assert.StartsWith("Severity must be between 1 (inclusive) and 24 (inclusive).", exception.Message);
-        Assert.Equal(level, (int)exception.ActualValue!);
+        Assert.Multiple(
+            () => Assert.Equal(text, severityText),
+            () => Assert.Equal(number, severityNumber));
+        var entry = Assert.Single(_logger.Entries);
+        Assert.Multiple(
+            () => Assert.Equal(SentryLevel.Debug, entry.Level),
+            () => Assert.Equal($$"""Log level {0} out of range ... clamping to {{clamp}} value {1} ({2})""", entry.Message),
+            () => Assert.Null(entry.Exception),
+            () => Assert.Equal([@enum, number, text], entry.Args));
     }
 
     public static TheoryData<int, string, int?> SeverityTextAndSeverityNumber()