feat: options.AddProfilingIntegration() (#3660)

* feat: options.AddProfilingIntegration()

* chore: update changelog

* chore: update changelog

* chore: add ProfilingIntegration to cocoa

* check prior to adding the default integration

---------

Co-authored-by: Bruno Garcia <[email protected]>

Author: vaind

CHANGELOG.md

@@ -17,6 +17,7 @@
 ### Features
 - Added support for `.NET 9` (preview) ([#3699](https://github.com/getsentry/sentry-dotnet/pull/3699))
 - libsentrysupplemental.so now supports 16 KB page sizes on Android ([#3723](https://github.com/getsentry/sentry-dotnet/pull/3723))
+- Added `SentryOptions` extension for profiling: `options.AddProfilingIntegration()` ([#3660](https://github.com/getsentry/sentry-dotnet/pull/3660))
 
 ### Fixes
 

samples/Sentry.Samples.AspNetCore.WebAPI.Profiling/Program.cs

@@ -3,7 +3,7 @@
 builder.WebHost.UseSentry(o =>
 {
     o.Dsn = "https://[email protected]/5428537";
-    o.AddIntegration(new ProfilingIntegration());
+    o.AddProfilingIntegration();
     o.ProfilesSampleRate = 0.1;
     o.TracesSampleRate = 1.0;
 });

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

@@ -22,7 +22,7 @@ private static void Main()
             // Debugging
             options.ShutdownTimeout = TimeSpan.FromMinutes(5);
 
-            options.AddIntegration(new ProfilingIntegration(TimeSpan.FromMilliseconds(500)));
+            options.AddProfilingIntegration(TimeSpan.FromMilliseconds(500));
         }))
         {
             var tx = SentrySdk.StartTransaction("app", "run");

src/Sentry.Profiling/ProfilingIntegration.cs

@@ -42,5 +42,9 @@ public void Register(IHub hub, SentryOptions options)
                 options.LogError(e, "Failed to initialize the profiler");
             }
         }
+        else
+        {
+            options.LogInfo("Profiling Integration is disabled because profiling is disabled by configuration.");
+        }
     }
 }

src/Sentry.Profiling/SentryOptionsProfilingExtensions.cs

@@ -0,0 +1,44 @@
+using Sentry.Extensibility;
+using Sentry.Profiling;
+
+namespace Sentry;
+
+/// <summary>
+/// The additional Sentry Options extensions from Sentry Profiling.
+/// </summary>
+[EditorBrowsable(EditorBrowsableState.Never)]
+public static class SentryOptionsProfilingExtensions
+{
+    /// <summary>
+    /// Adds ProfilingIntegration to Sentry.
+    /// </summary>
+    /// <param name="options">The Sentry options.</param>
+    /// <param name="startupTimeout">
+    /// If not given or TimeSpan.Zero, then the profiler initialization is asynchronous.
+    /// This is useful for applications that need to start quickly. The profiler will start in the background
+    /// and will be ready to capture transactions that have started after the profiler has started.
+    ///
+    /// If given a non-zero timeout, profiling startup blocks up to the given amount of time. If the timeout is reached
+    /// and the profiler session hasn't started yet, the execution is unblocked and behaves as the async startup,
+    /// i.e. transactions will be profiled only after the session is eventually started.
+    /// </param>
+    public static void AddProfilingIntegration(this SentryOptions options, TimeSpan startupTimeout = default)
+    {
+        if (options.HasIntegration<ProfilingIntegration>())
+        {
+            options.LogWarning($"{nameof(ProfilingIntegration)} has already been added. The second call to {nameof(AddProfilingIntegration)} will be ignored.");
+            return;
+        }
+
+        options.AddIntegration(new ProfilingIntegration(startupTimeout));
+    }
+
+    /// <summary>
+    /// Disables the Profiling integration.
+    /// </summary>
+    /// <param name="options">The SentryOptions to remove the integration from.</param>
+    public static void DisableProfilingIntegration(this SentryOptions options)
+    {
+        options.RemoveIntegration<ProfilingIntegration>();
+    }
+}

src/Sentry/Platforms/Cocoa/ProfilingIntegration.cs

@@ -0,0 +1,31 @@
+using Sentry.Extensibility;
+using Sentry.Integrations;
+
+namespace Sentry.Cocoa;
+
+/// <summary>
+/// Enables transaction performance profiling.
+/// </summary>
+public class ProfilingIntegration : ISdkIntegration
+{
+    /// <inheritdoc/>
+    public void Register(IHub hub, SentryOptions options)
+    {
+        if (options.IsProfilingEnabled)
+        {
+            try
+            {
+                options.LogDebug("Profiling is enabled, attaching native SDK profiler factory");
+                options.TransactionProfilerFactory ??= new CocoaProfilerFactory(options);
+            }
+            catch (Exception e)
+            {
+                options.LogError(e, "Failed to initialize the profiler");
+            }
+        }
+        else
+        {
+            options.LogInfo("Profiling Integration is disabled because profiling is disabled by configuration.");
+        }
+    }
+}

src/Sentry/Platforms/Cocoa/SentryOptions.cs

@@ -1,4 +1,6 @@
 using ObjCRuntime;
+using Sentry.Cocoa;
+using Sentry.Extensibility;
 
 // ReSharper disable once CheckNamespace
 namespace Sentry;
@@ -215,4 +217,38 @@ public void AddInAppInclude(string prefix)
             InAppIncludes.Add(prefix);
         }
     }
+
+    // We actually add the profiling integration automatically in InitSentryCocoaSdk().
+    // However, if user calls AddProfilingIntegration() multiple times, we print a warning, as usual.
+    private bool _profilingIntegrationAddedByUser = false;
+
+    /// <summary>
+    /// Adds ProfilingIntegration to Sentry.
+    /// </summary>
+    /// <param name="startupTimeout">
+    /// Unused, only here so that the signature is the same as AddProfilingIntegration() from package Sentry.Profiling.
+    /// </param>
+    public void AddProfilingIntegration(TimeSpan startupTimeout = default)
+    {
+        if (HasIntegration<ProfilingIntegration>())
+        {
+            if (_profilingIntegrationAddedByUser)
+            {
+                DiagnosticLogger?.LogWarning($"{nameof(ProfilingIntegration)} has already been added. The second call to {nameof(AddProfilingIntegration)} will be ignored.");
+            }
+            return;
+        }
+
+        _profilingIntegrationAddedByUser = true;
+        AddIntegration(new ProfilingIntegration());
+    }
+
+    /// <summary>
+    /// Disables the Profiling integration.
+    /// </summary>
+    public void DisableProfilingIntegration()
+    {
+        _profilingIntegrationAddedByUser = false;
+        RemoveIntegration<ProfilingIntegration>();
+    }
 }

src/Sentry/Platforms/Cocoa/SentrySdk.cs

@@ -185,12 +185,11 @@ private static void InitSentryCocoaSdk(SentryOptions options)
         options.EnableScopeSync = true;
         options.ScopeObserver = new CocoaScopeObserver(options);
 
-        if (options.IsProfilingEnabled)
+        // Note: don't use AddProfilingIntegration as it would print a warning if user used it too.
+        if (!options.HasIntegration<ProfilingIntegration>())
         {
-            options.LogDebug("Profiling is enabled, attaching native SDK profiler factory");
-            options.TransactionProfilerFactory ??= new CocoaProfilerFactory(options);
+            options.AddIntegration(new ProfilingIntegration());
         }
-
         // TODO: Pause/Resume
     }
 

src/Sentry/SentrySdk.cs

@@ -102,7 +102,7 @@ internal static IHub InitHub(SentryOptions options)
 #endif
         {
             LogWarningIfProfilingMisconfigured(options, ", because ProfilingIntegration from package Sentry.Profiling" +
-            " hasn't been registered. You can do that by calling 'options.AddIntegration(new ProfilingIntegration())'");
+            " hasn't been registered. You can do that by calling 'options.AddProfilingIntegration()'");
         }
 #endif
 

test/Sentry.Profiling.Tests/ProfilingSentryOptionsExtensionsTests.cs

@@ -0,0 +1,76 @@
+namespace Sentry.Profiling.Tests;
+
+#nullable enable
+
+[UsesVerify]
+
+public class ProfilingSentryOptionsExtensionsTests
+{
+    private readonly InMemoryDiagnosticLogger _logger = new();
+    private readonly SentryOptions _options = new()
+    {
+        Dsn = ValidDsn,
+        AutoSessionTracking = false,
+        IsGlobalModeEnabled = true,
+        BackgroundWorker = Substitute.For<IBackgroundWorker>(),
+        Debug = true,
+
+        // Set explicitly for this test in case the defaults change in the future.
+        TracesSampleRate = 0.0,
+        TracesSampler = null
+    };
+
+    public ProfilingSentryOptionsExtensionsTests()
+    {
+        _options.DiagnosticLogger = _logger;
+        _options.AddProfilingIntegration();
+    }
+
+    private Hub GetSut() => new(_options, Substitute.For<ISentryClient>());
+
+    private static IEnumerable<ISdkIntegration> GetIntegrations(ISentryClient hub) =>
+        hub.GetSentryOptions()?.Integrations ?? Enumerable.Empty<ISdkIntegration>();
+
+    [Fact]
+    public void Integration_DisabledWithDefaultOptions()
+    {
+        using var hub = GetSut();
+        var integrations = GetIntegrations(hub);
+        Assert.Contains(_logger.Entries, x => x.Message == "Profiling Integration is disabled because profiling is disabled by configuration."
+                                                     && x.Level == SentryLevel.Info);
+    }
+
+    [Fact]
+    public void Integration_EnabledBySampleRate()
+    {
+        _options.TracesSampleRate = 1.0;
+        _options.ProfilesSampleRate = 1.0;
+
+        using var hub = GetSut();
+        var integrations = GetIntegrations(hub);
+        Assert.Contains(integrations, i => i is ProfilingIntegration);
+    }
+
+    [Fact]
+    public void DisableProfilingIntegration_RemovesProfilingIntegration()
+    {
+        _options.TracesSampleRate = 1.0;
+        _options.ProfilesSampleRate = 1.0;
+        _options.DisableProfilingIntegration();
+
+        using var hub = GetSut();
+        var integrations = GetIntegrations(hub);
+        Assert.DoesNotContain(integrations, i => i is ProfilingIntegration);
+    }
+
+    [Fact]
+    public void AddProfilingIntegration_DoesntDuplicate()
+    {
+        var options = new SentryOptions();
+
+        options.AddProfilingIntegration();
+        options.AddProfilingIntegration();
+
+        Assert.Single(options.Integrations, x => x is ProfilingIntegration);
+    }
+}