docs(logs): add XML comments indicating that logs will be ignored on delegate exceptions

Author: Flash0ver

src/Sentry/SentryOptions.cs

@@ -534,6 +534,7 @@ public void SetBeforeBreadcrumb(Func<Breadcrumb, Breadcrumb?> beforeBreadcrumb)
 
     /// <summary>
     /// Sets a callback function to be invoked before sending the log to Sentry.
+    /// When the delegate throws an <see cref="Exception"/> during invocation, the log will not be captured.
     /// <para>This API is experimental and it may change in the future.</para>
     /// </summary>
     /// <remarks>

src/Sentry/SentryStructuredLogger.cs

@@ -40,6 +40,9 @@ internal SentryStructuredLogger(IHub hub, IInternalScopeManager? scopeManager, S
     /// 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>
+    /// <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>
     public void LogTrace(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
         if (IsEnabled)
@@ -52,6 +55,9 @@ public void LogTrace(string template, object[]? parameters = null, Action<Sentry
     /// 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>
+    /// <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>
     [Experimental(DiagnosticId.ExperimentalFeature)]
     public void LogDebug(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
@@ -65,6 +71,9 @@ public void LogDebug(string template, object[]? parameters = null, Action<Sentry
     /// 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>
+    /// <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>
     [Experimental(DiagnosticId.ExperimentalFeature)]
     public void LogInfo(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
@@ -78,6 +87,9 @@ public void LogInfo(string template, object[]? parameters = null, Action<SentryL
     /// 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>
+    /// <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>
     [Experimental(DiagnosticId.ExperimentalFeature)]
     public void LogWarning(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
@@ -91,6 +103,9 @@ public void LogWarning(string template, object[]? parameters = null, Action<Sent
     /// 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>
+    /// <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>
     [Experimental(DiagnosticId.ExperimentalFeature)]
     public void LogError(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
@@ -104,6 +119,9 @@ public void LogError(string template, object[]? parameters = null, Action<Sentry
     /// 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>
+    /// <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>
     [Experimental(DiagnosticId.ExperimentalFeature)]
     public void LogFatal(string template, object[]? parameters = null, Action<SentryLog>? configureLog = null)
     {
@@ -115,7 +133,7 @@ public void LogFatal(string template, object[]? parameters = null, Action<Sentry
 
     private void CaptureLog(SentryLogLevel level, string template, object[]? parameters, Action<SentryLog>? configureLog)
     {
-        Debug.Assert(_options is not null);
+        Debug.Assert(IsEnabled);
 
         var timestamp = _clock.GetUtcNow();