Added StartTimer extension method to IMetricAggregator (#3075)

Author: jamescrosswell

CHANGELOG.md

@@ -12,6 +12,10 @@ If you have conflicts, you can opt-out by adding the following to your `csproj`:
 </PropertyGroup>
 ```
 
+### Features
+
+- Timing metrics can now be captured with `SentrySdk.Metrics.StartTimer` ([#3075](https://github.com/getsentry/sentry-dotnet/pull/3075))
+
 ### Fixes
 
 - Fixed an issue with tag values in metrics not being properly serialized ([#3065](https://github.com/getsentry/sentry-dotnet/pull/3065))

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

@@ -15,6 +15,8 @@ private static void Main()
 
                    options.Debug = true;
                    options.StackTraceMode = StackTraceMode.Enhanced;
+                   options.SampleRate = 1.0f; // Not recommended in production - may adversely impact quota
+                   options.TracesSampleRate = 1.0f; // Not recommended in production - may adversely impact quota
                    // Initialize some (non null) ExperimentalMetricsOptions to enable Sentry Metrics,
                    options.ExperimentalMetrics = new ExperimentalMetricsOptions
                    {
@@ -24,22 +26,17 @@ private static void Main()
                }))
         {
             System.Console.WriteLine("Measure, Yeah, Measure!");
+            Action[] actions =
+            [
+                () => PlaySetBingo(10),
+                () => CreateRevenueGauge(100),
+                () => MeasureShrimp(30),
+            ];
             while (true)
             {
                 // Perform your task here
-                switch (Roll.Next(1,3))
-                {
-                    case 1:
-                        PlaySetBingo(10);
-                        break;
-                    case 2:
-                        CreateRevenueGauge(100);
-                        break;
-                    case 3:
-                        MeasureShrimp(30);
-                        break;
-                }
-
+                var actionIdx = Roll.Next(0, actions.Length);
+                actions[actionIdx]();
 
                 // Optional: Delay to prevent tight looping
                 var sleepTime = Roll.Next(1, 10);
@@ -60,9 +57,10 @@ private static void PlaySetBingo(int attempts)
     {
         var solution = new[] { 3, 5, 7, 11, 13, 17 };
 
-        // The Timing class creates a distribution that is designed to measure the amount of time it takes to run code
+        // StartTimer creates a distribution that is designed to measure the amount of time it takes to run code
         // blocks. By default it will use a unit of Seconds - we're configuring it to use milliseconds here though.
-        using (new Timing("bingo", MeasurementUnit.Duration.Millisecond))
+        // The return value is an IDisposable and the timer will stop when the timer is disposed of.
+        using (SentrySdk.Metrics.StartTimer("bingo", MeasurementUnit.Duration.Millisecond))
         {
             for (var i = 0; i < attempts; i++)
             {
@@ -78,7 +76,7 @@ private static void PlaySetBingo(int attempts)
 
     private static void CreateRevenueGauge(int sampleCount)
     {
-        using (new Timing(nameof(CreateRevenueGauge), MeasurementUnit.Duration.Millisecond))
+        using (SentrySdk.Metrics.StartTimer(nameof(CreateRevenueGauge), MeasurementUnit.Duration.Millisecond))
         {
             for (var i = 0; i < sampleCount; i++)
             {
@@ -92,7 +90,7 @@ private static void CreateRevenueGauge(int sampleCount)
 
     private static void MeasureShrimp(int sampleCount)
     {
-        using (new Timing(nameof(MeasureShrimp), MeasurementUnit.Duration.Millisecond))
+        using (SentrySdk.Metrics.StartTimer(nameof(MeasureShrimp), MeasurementUnit.Duration.Millisecond))
         {
             for (var i = 0; i < sampleCount; i++)
             {

src/Sentry/DisabledMetricAggregator.cs

@@ -37,6 +37,14 @@ public void Timing(string key, double value, MeasurementUnit.Duration unit = Mea
         // No Op
     }
 
+    public IDisposable StartTimer(string key, MeasurementUnit.Duration unit = MeasurementUnit.Duration.Second,
+        IDictionary<string, string>? tags = null,
+        int stackLevel = 1)
+    {
+        // No Op
+        return NoOpDisposable.Instance;
+    }
+
     public Task FlushAsync(bool force = true, CancellationToken cancellationToken = default)
     {
         // No Op
@@ -48,3 +56,14 @@ public void Dispose()
         // No Op
     }
 }
+
+internal class NoOpDisposable : IDisposable
+{
+    private static readonly Lazy<NoOpDisposable> LazyInstance = new();
+    internal static NoOpDisposable Instance => LazyInstance.Value;
+
+    public void Dispose()
+    {
+        // No Op
+    }
+}

src/Sentry/Extensibility/DisabledHub.cs

@@ -1,3 +1,6 @@
+using Sentry.Protocol.Envelopes;
+using Sentry.Protocol.Metrics;
+
 namespace Sentry.Extensibility;
 
 /// <summary>
@@ -133,6 +136,14 @@ public void BindClient(ISentryClient client)
     {
     }
 
+    /// <summary>
+    /// No-Op.
+    /// </summary>
+    public bool CaptureEnvelope(Envelope envelope)
+    {
+        return false;
+    }
+
     /// <summary>
     /// No-Op.
     /// </summary>

src/Sentry/Extensibility/HubAdapter.cs

@@ -1,4 +1,6 @@
 using Sentry.Infrastructure;
+using Sentry.Protocol.Envelopes;
+using Sentry.Protocol.Metrics;
 
 namespace Sentry.Extensibility;
 
@@ -209,6 +211,9 @@ public SentryId CaptureEvent(SentryEvent evt)
     public SentryId CaptureEvent(SentryEvent evt, Scope? scope)
         => SentrySdk.CaptureEvent(evt, scope, null);
 
+    /// <inheritdoc cref="ISentryClient.CaptureEnvelope"/>
+    public bool CaptureEnvelope(Envelope envelope) => SentrySdk.CurrentHub.CaptureEnvelope(envelope);
+
     /// <summary>
     /// Forwards the call to <see cref="SentrySdk"/>.
     /// </summary>

src/Sentry/IHub.cs

@@ -1,3 +1,5 @@
+using Sentry.Protocol.Metrics;
+
 namespace Sentry;
 
 /// <summary>
@@ -19,6 +21,11 @@ public interface IHub :
     /// </summary>
     SentryId LastEventId { get; }
 
+    /// <summary>
+    /// <inheritdoc cref="IMetricAggregator"/>
+    /// </summary>
+    IMetricAggregator Metrics { get; }
+
     /// <summary>
     /// Starts a transaction.
     /// </summary>

src/Sentry/IMetricAggregator.cs

@@ -96,6 +96,18 @@ void Timing(string key,
         DateTimeOffset? timestamp = null,
         int stackLevel = 1);
 
+    /// <summary>
+    /// Measures the time it takes to run a given code block and emits this as a metric.
+    /// </summary>
+    /// <example>
+    /// using (SentrySdk.Metrics.StartTimer("my-operation"))
+    /// {
+    ///     ...
+    /// }
+    /// </example>
+    IDisposable StartTimer(string key, MeasurementUnit.Duration unit = MeasurementUnit.Duration.Second,
+        IDictionary<string, string>? tags = null, int stackLevel = 1);
+
     /// <summary>
     /// Flushes any flushable metrics and/or code locations.
     /// If <paramref name="force"/> is true then the cutoff is ignored and all metrics are flushed.

src/Sentry/IMetricHub.cs

@@ -0,0 +1,21 @@
+using Sentry.Protocol.Metrics;
+
+namespace Sentry;
+
+internal interface IMetricHub
+{
+    /// <summary>
+    /// Captures one or more metrics to be sent to Sentry.
+    /// </summary>
+    void CaptureMetrics(IEnumerable<Metric> metrics);
+
+    /// <summary>
+    /// Captures one or more <see cref="CodeLocations"/> to be sent to Sentry.
+    /// </summary>
+    void CaptureCodeLocations(CodeLocations codeLocations);
+
+    /// <summary>
+    /// Starts a child span for the current transaction or, if there is no active transaction, starts a new transaction.
+    /// </summary>
+    ISpan StartSpan(string operation, string description);
+}

src/Sentry/ISentryClient.cs

@@ -1,3 +1,6 @@
+using Sentry.Protocol.Envelopes;
+using Sentry.Protocol.Metrics;
+
 namespace Sentry;
 
 /// <summary>
@@ -10,6 +13,13 @@ public interface ISentryClient
     /// </summary>
     bool IsEnabled { get; }
 
+    /// <summary>
+    /// Capture an envelope and queue it.
+    /// </summary>
+    /// <param name="envelope">The envelope.</param>
+    /// <returns>true if the enveloped was queued, false otherwise.</returns>
+    bool CaptureEnvelope(Envelope envelope);
+
     /// <summary>
     /// Capture the event
     /// </summary>
@@ -68,9 +78,4 @@ public interface ISentryClient
     /// <param name="timeout">The amount of time allowed for flushing.</param>
     /// <returns>A task to await for the flush operation.</returns>
     Task FlushAsync(TimeSpan timeout);
-
-    /// <summary>
-    /// <inheritdoc cref="IMetricAggregator"/>
-    /// </summary>
-    IMetricAggregator Metrics { get; }
 }

src/Sentry/Internal/Hub.cs

@@ -1,9 +1,11 @@
 using Sentry.Extensibility;
 using Sentry.Infrastructure;
+using Sentry.Protocol.Envelopes;
+using Sentry.Protocol.Metrics;
 
 namespace Sentry.Internal;
 
-internal class Hub : IHub, IDisposable
+internal class Hub : IHub, IMetricHub, IDisposable
 {
     private readonly object _sessionPauseLock = new();
 
@@ -59,7 +61,14 @@ internal Hub(
             PushScope();
         }
 
-        Metrics = _ownedClient.Metrics;
+        if (options.ExperimentalMetrics is not null)
+        {
+            Metrics = new MetricAggregator(options, this);
+        }
+        else
+        {
+            Metrics = new DisabledMetricAggregator();
+        }
 
         foreach (var integration in options.Integrations)
         {
@@ -394,6 +403,8 @@ public SentryId CaptureEvent(SentryEvent evt, Hint? hint, Action<Scope> configur
         }
     }
 
+    public bool CaptureEnvelope(Envelope envelope) => _ownedClient.CaptureEnvelope(envelope);
+
     public SentryId CaptureEvent(SentryEvent evt, Scope? scope = null, Hint? hint = null)
     {
         if (!IsEnabled)
@@ -486,6 +497,57 @@ public void CaptureTransaction(SentryTransaction transaction, Scope? scope, Hint
         }
     }
 
+    /// <inheritdoc cref="IMetricHub.CaptureMetrics"/>
+    public void CaptureMetrics(IEnumerable<Metric> metrics)
+    {
+        if (!IsEnabled)
+        {
+            return;
+        }
+
+        Metric[]? enumerable = null;
+        try
+        {
+            enumerable = metrics as Metric[] ?? metrics.ToArray();
+            _options.LogDebug("Capturing metrics.");
+            _ownedClient.CaptureEnvelope(Envelope.FromMetrics(metrics));
+        }
+        catch (Exception e)
+        {
+            var metricEventIds = enumerable?.Select(m => m.EventId).ToArray() ?? [];
+            _options.LogError(e, "Failure to capture metrics: {0}", string.Join(",", metricEventIds));
+        }
+    }
+
+    /// <inheritdoc cref="IMetricHub.CaptureCodeLocations"/>
+    public void CaptureCodeLocations(CodeLocations codeLocations)
+    {
+        if (!IsEnabled)
+        {
+            return;
+        }
+
+        try
+        {
+            _options.LogDebug("Capturing code locations for period: {0}", codeLocations.Timestamp);
+            _ownedClient.CaptureEnvelope(Envelope.FromCodeLocations(codeLocations));
+        }
+        catch (Exception e)
+        {
+            _options.LogError(e, "Failure to capture code locations");
+        }
+    }
+
+    /// <inheritdoc cref="IMetricHub.StartSpan"/>
+    public ISpan StartSpan(string operation, string description)
+    {
+        ITransactionTracer? currentTransaction = null;
+        ConfigureScope(s => currentTransaction = s.Transaction);
+        return currentTransaction is {} transaction
+            ? transaction.StartChild(operation, description)
+            : this.StartTransaction(operation, description);
+    }
+
     public void CaptureSession(SessionUpdate sessionUpdate)
     {
         if (!IsEnabled)
@@ -527,7 +589,7 @@ public void Dispose()
 
         try
         {
-            _ownedClient.Metrics.FlushAsync().ContinueWith(_ =>
+            Metrics.FlushAsync().ContinueWith(_ =>
                 _ownedClient.FlushAsync(_options.ShutdownTimeout).Wait()
             ).ConfigureAwait(false).GetAwaiter().GetResult();
         }