feat(logs): rework method overloads of Structured Logger

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features
 
 - Experimental _Structured Logs_:
+  - Redesign SDK Logger APIs to allow usage of `params` ([#4451](https://github.com/getsentry/sentry-dotnet/pull/4451))
   - Shorten the `key` names of `Microsoft.Extensions.Logging` attributes ([#4450](https://github.com/getsentry/sentry-dotnet/pull/4450))
 
 ### Fixes

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

@@ -37,7 +37,7 @@
     // 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.
+    // This option enables Sentry Logs created via SentrySdk.Experimental.Logger.
     options.Experimental.EnableLogs = true;
     options.Experimental.SetBeforeSendLog(static log =>
     {
@@ -94,7 +94,8 @@ async Task SecondFunction()
         SentrySdk.CaptureException(exception);
         span.Finish(exception);
 
-        SentrySdk.Experimental.Logger.LogError("Error with message: {0}", [exception.Message], static log => log.SetAttribute("method", nameof(SecondFunction)));
+        SentrySdk.Experimental.Logger.LogError(static log => log.SetAttribute("method", nameof(SecondFunction)),
+            "Error with message: {0}", exception.Message);
     }
 
     span.Finish();
@@ -108,7 +109,8 @@ async Task ThirdFunction()
         // Simulate doing some work
         await Task.Delay(100);
 
-        SentrySdk.Experimental.Logger.LogFatal("Crash imminent!", [], static log => log.SetAttribute("suppress", true));
+        SentrySdk.Experimental.Logger.LogFatal(static log => log.SetAttribute("suppress", true),
+            "Crash imminent!");
 
         // This is an example of an unhandled exception.  It will be captured automatically.
         throw new InvalidOperationException("Something happened that crashed the app!");

src/Sentry/SentryStructuredLogger.Format.cs

@@ -0,0 +1,156 @@
+using Sentry.Infrastructure;
+
+namespace Sentry;
+
+public abstract partial class SentryStructuredLogger
+{
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Trace"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogTrace(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Trace, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Trace"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogTrace(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Trace, template, parameters, configureLog);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Debug"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogDebug(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Debug, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Debug"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogDebug(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Debug, template, parameters, configureLog);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Info"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogInfo(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Info, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Info"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogInfo(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Info, template, parameters, configureLog);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Warning"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogWarning(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Warning, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Warning"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogWarning(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Warning, template, parameters, configureLog);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Error"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogError(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Error, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Error"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogError(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Error, template, parameters, configureLog);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Fatal"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogFatal(string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Fatal, template, parameters, null);
+    }
+
+    /// <summary>
+    /// Creates and sends a structured log to Sentry, with severity <see cref="SentryLogLevel.Fatal"/>, when enabled and sampled.
+    /// <para>This API is experimental and it may change in the future.</para>
+    /// </summary>
+    /// <param name="configureLog">A delegate to set attributes on the <see cref="SentryLog"/>. When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.</param>
+    /// <param name="template">A formattable <see langword="string"/>. When incompatible with the <paramref name="parameters"/>, the log will not be captured. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    /// <param name="parameters">The arguments to the <paramref name="template"/>. See <see href="https://learn.microsoft.com/dotnet/api/system.string.format">System.String.Format</see>.</param>
+    [Experimental(DiagnosticId.ExperimentalFeature)]
+    public void LogFatal(Action<SentryLog> configureLog, string template, params object[] parameters)
+    {
+        CaptureLog(SentryLogLevel.Fatal, template, parameters, configureLog);
+    }
+}