feat(metrics): Add timing API (#3812)

philipphofmann · web-flow · commit c83ffd949311 · 2024-04-04T16:09:44.000+02:00
Add the timing API to measure the duration of a closure.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Add timing API for Metrics (#3812):
+
 ## 8.23.0
 
 ### Features
diff --git a/Samples/iOS-Swift/iOS-Swift/ErrorsViewController.swift b/Samples/iOS-Swift/iOS-Swift/ErrorsViewController.swift
@@ -13,6 +13,10 @@ class ErrorsViewController: UIViewController {
         SentrySDK.reportFullyDisplayed()
         
         SentrySDK.metrics.increment(key: "load.errors.view.controller")
+        
+        SentrySDK.metrics.timing(key: "timing.some.delayed") {
+            Thread.sleep(forTimeInterval: 0.01)
+        }
     }
 
     @IBAction func useAfterFree(_ sender: UIButton) {
diff --git a/Sources/Sentry/SentryHub.m b/Sources/Sentry/SentryHub.m
@@ -701,19 +701,7 @@ - (void)close
     SENTRY_LOG_DEBUG(@"Closed the Hub.");
 }
 
-- (LocalMetricsAggregator *_Nullable)getLocalMetricsAggregator
-{
-    id<SentrySpan> currentSpan = _scope.span;
-
-    // We don't want to add them LocalMetricsAggregator to the SentrySpan protocol and make it
-    // public. Instead, we check if the span responds to the getLocalMetricsAggregator which, every
-    // span should do.
-    if ([currentSpan isKindOfClass:SentrySpan.class]) {
-        return [(SentrySpan *)currentSpan getLocalMetricsAggregator];
-    }
-
-    return nil;
-}
+#pragma mark - SentryMetricsAPIDelegate
 
 - (NSDictionary<NSString *, NSString *> *)getDefaultTagsForMetrics
 {
@@ -733,6 +721,22 @@ - (LocalMetricsAggregator *_Nullable)getLocalMetricsAggregator
     return defaultTags;
 }
 
+- (id<SentrySpan> _Nullable)getCurrentSpan
+{
+    return _scope.span;
+}
+
+- (LocalMetricsAggregator *_Nullable)getLocalMetricsAggregatorWithSpan:(id<SentrySpan>)span
+{
+    // We don't want to add them LocalMetricsAggregator to the SentrySpan protocol and make it
+    // public. Instead, we check if the span responds to the getLocalMetricsAggregator which, every
+    // span should do.
+    if ([span isKindOfClass:SentrySpan.class]) {
+        return [(SentrySpan *)span getLocalMetricsAggregator];
+    }
+    return nil;
+}
+
 #pragma mark - Protected
 
 - (NSMutableArray<NSString *> *)trimmedInstalledIntegrationNames
diff --git a/Sources/Swift/Metrics/SentryMetricsAPI.swift b/Sources/Swift/Metrics/SentryMetricsAPI.swift
@@ -2,9 +2,16 @@
 import Foundation
 
 @objc protocol SentryMetricsAPIDelegate: AnyObject {
+    
     func getDefaultTagsForMetrics() -> [String: String]
     
-    func getLocalMetricsAggregator() -> LocalMetricsAggregator?
+    func getCurrentSpan() -> Span?
+    
+    // We don't want to add the LocalMetricsAggregator to the SpanProtocol
+    // because it would be public then. Exposing the LocalMetricsAggregator
+    // on the Span internally in Swift is a bit tricky, so we ask the
+    // delegate written in ObjC for it.
+    func getLocalMetricsAggregator(span: Span) -> LocalMetricsAggregator?
 }
 
 /// Using SentryBeforeEmitMetricCallback of SentryDefines.h leads to compiler errors because of
@@ -14,11 +21,14 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
 @objc public class SentryMetricsAPI: NSObject {
 
     private let aggregator: MetricsAggregator
+    private let currentDate: SentryCurrentDateProvider
     
     private weak var delegate: SentryMetricsAPIDelegate?
 
     @objc init(enabled: Bool, client: SentryMetricsClient, currentDate: SentryCurrentDateProvider, dispatchQueue: SentryDispatchQueueWrapper, random: SentryRandomProtocol, beforeEmitMetric: BeforeEmitMetricCallback?) {
         
+        self.currentDate = currentDate
+        
         if enabled {
             self.aggregator = BucketMetricsAggregator(client: client, currentDate: currentDate, dispatchQueue: dispatchQueue, random: random, beforeEmitMetric: beforeEmitMetric ?? { _, _ in true })
         } else {
@@ -38,7 +48,8 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
     /// - Parameter tags: Tags to associate with the metric.
     @objc public func increment(key: String, value: Double = 1.0, unit: MeasurementUnit = .none, tags: [String: String] = [:]) {
         let mergedTags = mergeDefaultTagsInto(tags: tags)
-        aggregator.increment(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: delegate?.getLocalMetricsAggregator())
+        
+        aggregator.increment(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: getLocalMetricsAggregator())
     }
     
     /// Emits a Gauge metric.
@@ -50,7 +61,7 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
     @objc
     public func gauge(key: String, value: Double, unit: MeasurementUnit = .none, tags: [String: String] = [:]) {
         let mergedTags = mergeDefaultTagsInto(tags: tags)
-        aggregator.gauge(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: delegate?.getLocalMetricsAggregator())
+        aggregator.gauge(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: getLocalMetricsAggregator())
     }
     
     /// Emits a Distribution metric.
@@ -62,7 +73,7 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
     @objc
     public func distribution(key: String, value: Double, unit: MeasurementUnit = .none, tags: [String: String] = [:]) {
         let mergedTags = mergeDefaultTagsInto(tags: tags)
-        aggregator.distribution(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: delegate?.getLocalMetricsAggregator())
+        aggregator.distribution(key: key, value: value, unit: unit, tags: mergedTags, localMetricsAggregator: getLocalMetricsAggregator())
     }
     
     /// Emits a Set metric.
@@ -76,7 +87,40 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
         let mergedTags = mergeDefaultTagsInto(tags: tags)
         let crc32 = sentry_crc32ofString(value)
         
-        aggregator.set(key: key, value: crc32, unit: unit, tags: mergedTags, localMetricsAggregator: delegate?.getLocalMetricsAggregator())
+        aggregator.set(key: key, value: crc32, unit: unit, tags: mergedTags, localMetricsAggregator: getLocalMetricsAggregator())
+    }
+    
+    /// Measures how long it takes to run the given closure by emitting a distribution metric in seconds.
+    /// 
+    /// - Note: This method also creates a child span with the operation `metric.timing` and the 
+    ///     description `key` if a span is bound to the scope.
+    ///
+    /// - Parameter key: A unique key identifying the metric.
+    /// - Parameter tags: Tags to associate with the metric.
+    public func timing<T>(key: String, tags: [String: String] = [:], _ closure: () throws -> T) rethrows -> T {
+        
+        guard let currentSpan = delegate?.getCurrentSpan() else {
+            return try closure()
+        }
+            
+        let span = currentSpan.startChild(operation: "metric.timing", description: key)
+        let aggregator = delegate?.getLocalMetricsAggregator(span: span)
+        
+        let mergedTags = mergeDefaultTagsInto(tags: tags)
+        for tag in mergedTags {
+            span.setTag(value: tag.value, key: tag.key)
+        }
+        
+        defer {
+            span.finish()
+            if let timestamp = span.timestamp, let startTimestamp = span.startTimestamp {
+                let duration = timestamp.timeIntervalSince(startTimestamp)
+                
+                self.aggregator.distribution(key: key, value: duration, unit: MeasurementUnitDuration.second, tags: mergedTags, localMetricsAggregator: aggregator)
+            }
+        }
+        
+        return try closure()
     }
 
     @objc public func close() {
@@ -93,5 +137,12 @@ typealias BeforeEmitMetricCallback = (String, [String: String]) -> Bool
         let defaultTags = delegate?.getDefaultTagsForMetrics() ?? [:]
         return tags.merging(defaultTags) { (tagValue, _) in tagValue }
     }
+    
+    private func getLocalMetricsAggregator() -> LocalMetricsAggregator? {
+        if let currentSpan = delegate?.getCurrentSpan() {
+            return delegate?.getLocalMetricsAggregator(span: currentSpan)
+        }
+        return nil
+    }
 
 }
diff --git a/Tests/SentryTests/Swift/Metrics/SentryMetricsAPITests.swift b/Tests/SentryTests/Swift/Metrics/SentryMetricsAPITests.swift
@@ -4,11 +4,34 @@ import Nimble
 import SentryTestUtils
 import XCTest
 
-final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
+final class SentryMetricsAPITests: XCTestCase {
     
-    func testInitWithDisabled_AllOperationsAreNoOps() throws {
+    override func tearDown() {
+        super.tearDown()
+        clearTestState()
+    }
+    
+    private func getSut(enabled: Bool = true) throws -> (SentryMetricsAPI, TestMetricsClient, TestCurrentDateProvider, TestHub, Options) {
+        
         let metricsClient = try TestMetricsClient()
-        let sut = SentryMetricsAPI(enabled: false, client: metricsClient, currentDate: SentryCurrentDateProvider(), dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: { _, _ in true })
+        let currentDate = TestCurrentDateProvider()
+        let sut = SentryMetricsAPI(enabled: enabled, client: metricsClient, currentDate: currentDate, dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: nil)
+        
+        SentryDependencyContainer.sharedInstance().dateProvider = currentDate
+        
+        let options = Options()
+        options.enableMetrics = true
+        
+        let testClient = try XCTUnwrap(TestClient(options: options))
+        let testHub = TestHub(client: testClient, andScope: Scope())
+        
+        sut.setDelegate(testHub as? SentryMetricsAPIDelegate)
+        
+        return (sut, metricsClient, currentDate, testHub, options)
+    }
+    
+    func testInitWithDisabled_AllOperationsAreNoOps() throws {
+        let (sut, metricsClient, _, _, _) = try getSut(enabled: false)
         
         sut.increment(key: "some", value: 1.0, unit: .none, tags: ["yeah": "sentry"])
         sut.gauge(key: "some", value: 1.0, unit: .none, tags: ["yeah": "sentry"])
@@ -21,9 +44,9 @@ final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
     }
     
     func testIncrement_EmitsIncrementMetric() throws {
-        let metricsClient = try TestMetricsClient()
-        let sut = SentryMetricsAPI(enabled: true, client: metricsClient, currentDate: SentryCurrentDateProvider(), dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: { _, _ in return true })
-        sut.setDelegate(self)
+        let (sut, metricsClient, _, _, _) = try getSut()
+        let delegate = TestSentryMetricsAPIDelegate()
+        sut.setDelegate(delegate)
         
         sut.increment(key: "key", value: 1.0, unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
         
@@ -43,9 +66,9 @@ final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
     }
     
     func testGauge_EmitsGaugeMetric() throws {
-        let metricsClient = try TestMetricsClient()
-        let sut = SentryMetricsAPI(enabled: true, client: metricsClient, currentDate: SentryCurrentDateProvider(), dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: { _, _ in return true })
-        sut.setDelegate(self)
+        let (sut, metricsClient, _, _, _) = try getSut()
+        let delegate = TestSentryMetricsAPIDelegate()
+        sut.setDelegate(delegate)
         
         sut.gauge(key: "key", value: 1.0, unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
         
@@ -65,9 +88,9 @@ final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
     }
     
     func testDistribution_EmitsDistributionMetric() throws {
-        let metricsClient = try TestMetricsClient()
-        let sut = SentryMetricsAPI(enabled: true, client: metricsClient, currentDate: SentryCurrentDateProvider(), dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: { _, _ in return true })
-        sut.setDelegate(self)
+        let (sut, metricsClient, _, _, _) = try getSut()
+        let delegate = TestSentryMetricsAPIDelegate()
+        sut.setDelegate(delegate)
         
         sut.distribution(key: "key", value: 1.0, unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
         sut.distribution(key: "key", value: 12.0, unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
@@ -88,9 +111,9 @@ final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
     }
     
     func testSet_EmitsSetMetric() throws {
-        let metricsClient = try TestMetricsClient()
-        let sut = SentryMetricsAPI(enabled: true, client: metricsClient, currentDate: SentryCurrentDateProvider(), dispatchQueue: SentryDispatchQueueWrapper(), random: SentryRandom(), beforeEmitMetric: { _, _ in return true })
-        sut.setDelegate(self)
+        let (sut, metricsClient, _, _, _) = try getSut()
+        let delegate = TestSentryMetricsAPIDelegate()
+        sut.setDelegate(delegate)
         
         sut.set(key: "key", value: "value1", unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
         sut.set(key: "key", value: "value1", unit: MeasurementUnitFraction.percent, tags: ["yeah": "sentry"])
@@ -111,11 +134,114 @@ final class SentryMetricsAPITests: XCTestCase, SentryMetricsAPIDelegate {
         expect(metric.tags) == ["yeah": "sentry", "some": "tag"]
     }
     
+    func testTiming_WhenNoCurrentSpan_NoSpanCreatedAndNoMetricEmitted() throws {
+        let (sut, metricsClient, _, _, _) = try getSut()
+        let delegate = TestSentryMetricsAPIDelegate()
+        sut.setDelegate(delegate)
+        
+        let errorMessage = "It's broken"
+        do {
+            try sut.timing(key: "key") {
+                throw MetricsAPIError.runtimeError(errorMessage)
+            }
+        } catch MetricsAPIError.runtimeError(let actualErrorMessage) {
+            expect(actualErrorMessage) == errorMessage
+        }
+        
+        expect(metricsClient.captureInvocations.count) == 0
+    }
+    
+    func testTiming_WithCurrentSpan_CapturesGaugeMetric() throws {
+        let (sut, metricsClient, currentDate, testHub, options) = try getSut()
+        
+        let transaction = testHub.startTransaction(name: "hello", operation: "operation", bindToScope: true)
+        
+        let errorMessage = "It's broken"
+        do {
+            try sut.timing(key: "key", tags: ["some": "tag"]) {
+                currentDate.setDate(date: currentDate.date().addingTimeInterval(1.0))
+                throw MetricsAPIError.runtimeError(errorMessage)
+            }
+        } catch MetricsAPIError.runtimeError(let actualErrorMessage) {
+            expect(actualErrorMessage) == errorMessage
+        }
+        
+        sut.flush()
+        transaction.finish()
+        
+        expect(metricsClient.captureInvocations.count) == 1
+        let buckets = try XCTUnwrap(metricsClient.captureInvocations.first)
+        
+        let bucket = try XCTUnwrap(buckets.first?.value)
+        expect(bucket.count) == 1
+        let metric = try XCTUnwrap(bucket.first as? DistributionMetric)
+        
+        expect(metric.key) == "key"
+        expect(metric.serialize()) == ["1.0"]
+        expect(metric.unit.unit) == MeasurementUnitDuration.second.unit
+        expect(metric.tags) == ["some": "tag", "release": options.releaseName, "environment": options.environment]
+    }
+    
+    func testTiming_WithCurrentSpan_CreatesSpanWithMetricsSummary() throws {
+        let (sut, _, currentDate, testHub, options) = try getSut()
+        
+        let transaction = testHub.startTransaction(name: "hello", operation: "operation", bindToScope: true)
+        
+        sut.timing(key: "key", tags: ["some": "tag"]) {
+            currentDate.setDate(date: currentDate.date().addingTimeInterval(1.0))
+        }
+        
+        transaction.finish()
+        
+        expect(testHub.capturedTransactionsWithScope.count) == 1
+        let serializedTransaction = try XCTUnwrap(testHub.capturedTransactionsWithScope.first?.transaction)
+        expect(serializedTransaction.count) != 0
+        
+        let spans = try XCTUnwrap(serializedTransaction["spans"] as? [[String: Any]])
+        expect(spans.count) == 1
+        let span = try XCTUnwrap(spans.first)
+        
+        expect(span["op"] as? String) == "metric.timing"
+        expect(span["description"] as? String) == "key"
+        expect(span["origin"] as? String) == "manual"
+        expect(span["start_timestamp"] as? Int) == 978_307_200
+        expect(span["timestamp"] as? Int) == 978_307_201
+        expect(span["parent_span_id"] as? String) == transaction.spanId.sentrySpanIdString
+        expect(span["tags"] as? [String: String]) == ["some": "tag", "release": options.releaseName, "environment": options.environment]
+        
+        let metricsSummary = try XCTUnwrap(span["_metrics_summary"] as? [String: [[String: Any]]])
+        expect(metricsSummary.count) == 1
+        
+        let bucket = try XCTUnwrap(metricsSummary["d:key@second"] )
+        expect(bucket.count) == 1
+        let metric = try XCTUnwrap(bucket.first)
+        expect(metric["min"] as? Double) == 1.0
+        expect(metric["max"] as? Double) == 1.0
+        expect(metric["count"] as? Int) == 1
+        expect(metric["sum"] as? Double) == 1.0
+    }
+    
+    enum MetricsAPIError: Error {
+        case runtimeError(String)
+    }
+}
+
+class TestSentryMetricsAPIDelegate: SentryMetricsAPIDelegate {
+    var currentSpan: SentrySpan?
+    
     func getDefaultTagsForMetrics() -> [String: String] {
         return ["some": "tag", "yeah": "not-taken"]
     }
     
     func getLocalMetricsAggregator() -> Sentry.LocalMetricsAggregator? {
-        return nil
+        return currentSpan?.getLocalMetricsAggregator()
+    }
+    
+    func getCurrentSpan() -> Span? {
+        return currentSpan
+    }
+    
+    func getLocalMetricsAggregator(span: Span) -> Sentry.LocalMetricsAggregator? {
+        return (span as? SentrySpan)?.getLocalMetricsAggregator()
     }
 }

Original file line number	Diff line number	Diff line change
`@@ -13,6 +13,10 @@ class ErrorsViewController: UIViewController {`
`13`	`13`	`SentrySDK.reportFullyDisplayed()`
`14`	`14`
`15`	`15`	`SentrySDK.metrics.increment(key: "load.errors.view.controller")`
	`16`	`+`
	`17`	`+ SentrySDK.metrics.timing(key: "timing.some.delayed") {`
	`18`	`+ Thread.sleep(forTimeInterval: 0.01)`
	`19`	`+ }`
`16`	`20`	`}`
`17`	`21`
`18`	`22`	`@IBAction func useAfterFree(_ sender: UIButton) {`