feat: Measure slow and frozen frames

CHANGELOG.md

@@ -6,6 +6,7 @@ fix: Operation names for auto instrumentation (#1164)
 
 ## 7.2.0-beta.0
 
+- feat: Measure slow and frozen frames (#1123)
 - feat: Measure app start time (#1111)
 - feat: Auto UI Performance Instrumentation (#1105, #1150, #1136, #1139, #1042)
 

Sentry.xcodeproj/xcshareddata/xcbaselines/63AA76641EB8CB2F00D153DE.xcbaseline/4487886E-B920-4AB1-99BD-1A9C5128C731.plist

@@ -4,6 +4,19 @@
 <dict>
 	<key>classNames</key>
 	<dict>
+		<key>SentryFramesTrackerTests</key>
+		<dict>
+			<key>testPerformanceOfTrackingFrames()</key>
+			<dict>
+				<key>com.apple.XCTPerformanceMetric_WallClockTime</key>
+				<dict>
+					<key>baselineAverage</key>
+					<real>0.0013329</real>
+					<key>baselineIntegrationDisplayName</key>
+					<string>Local Baseline</string>
+				</dict>
+			</dict>
+		</dict>
 		<key>SentryHttpTransportTests</key>
 		<dict>
 			<key>testPerformanceOfSending()</key>

Sources/Sentry/Public/SentryOptions.h

@@ -125,6 +125,11 @@ NS_SWIFT_NAME(Options)
  */
 @property (nonatomic, assign) BOOL enableAppStartMeasuring;
 
+/**
+ * Whether to enable measuring the rendering of frames of the UI or not. Default is YES.
+ */
+@property (nonatomic, assign) BOOL enableFrameRenderMeasuring;
+
 /**
  * The interval to end a session if the App goes to the background.
  */

Sources/Sentry/SentryFramesTracker.m

@@ -0,0 +1,140 @@
+#import "SentryFramesTracker.h"
+#import "SentryDisplayLinkWrapper.h"
+#import "SentryLog.h"
+#import "SentryOptions.h"
+#include <stdatomic.h>
+
+#if SENTRY_HAS_UIKIT
+#    import <UIKit/UIKit.h>
+
+static CFTimeInterval const SentryFrozenFrameThreshold = 0.7;
+static CFTimeInterval const SentryPreviousFrameInitalValue = -1;
+
+/**
+ * Relaxed memoring ordering is typical for incrementing counters. This operation only requires
+ * atomicity but not ordering or synchronization.
+ */
+static memory_order const SentryFramesMemoryOrder = memory_order_relaxed;
+
+@interface
+SentryFramesTracker ()
+
+@property (nonatomic, strong, readonly) SentryDisplayLinkWrapper *displayLinkWrapper;
+@property (nonatomic, assign, readonly) CFTimeInterval slowFrameThreshold;
+@property (nonatomic, assign) CFTimeInterval previousFrameTimestamp;
+
+@end
+
+@implementation SentryFramesTracker {
+
+    /**
+     * With 32 bit we can track frames with 120 fps for around 414 days (2^32 / (120* 60 * 60 *
+     * 24)).
+     */
+    atomic_uint_fast32_t _totalFrames;
+    atomic_uint_fast32_t _slowFrames;
+    atomic_uint_fast32_t _frozenFrames;
+}
+
++ (instancetype)sharedInstance
+{
+    static SentryFramesTracker *sharedInstance = nil;
+    static dispatch_once_t onceToken;
+    dispatch_once(&onceToken, ^{
+        sharedInstance =
+            [[self alloc] initWithDisplayLinkWrapper:[[SentryDisplayLinkWrapper alloc] init]];
+    });
+    return sharedInstance;
+}
+
+/** Internal constructor for testing */
+- (instancetype)initWithDisplayLinkWrapper:(SentryDisplayLinkWrapper *)displayLinkWrapper
+{
+    if (self = [super init]) {
+        _isRunning = NO;
+        _displayLinkWrapper = displayLinkWrapper;
+
+        // If we can't get the frame rate we assume it is 60.
+        double maximumFramesPerSecond = 60.0;
+        if (@available(iOS 10.3, tvOS 10.3, macCatalyst 13.0, *)) {
+            maximumFramesPerSecond = (double)UIScreen.mainScreen.maximumFramesPerSecond;
+        }
+
+        // Most frames take just a few microseconds longer than the optimal caculated duration.
+        // Therefore we substract one, because otherwise almost all frames would be slow.
+        _slowFrameThreshold = 1 / (maximumFramesPerSecond - 1);
+
+        [self resetFrames];
+    }
+    return self;
+}
+
+/** Internal for testing */
+- (void)setDisplayLinkWrapper:(SentryDisplayLinkWrapper *)displayLinkWrapper
+{
+    _displayLinkWrapper = displayLinkWrapper;
+}
+
+/** Internal for testing */
+- (void)resetFrames
+{
+    atomic_store_explicit(&_totalFrames, 0, SentryFramesMemoryOrder);
+    atomic_store_explicit(&_frozenFrames, 0, SentryFramesMemoryOrder);
+    atomic_store_explicit(&_slowFrames, 0, SentryFramesMemoryOrder);
+
+    self.previousFrameTimestamp = SentryPreviousFrameInitalValue;
+}
+
+- (void)start
+{
+    _isRunning = YES;
+    [_displayLinkWrapper linkWithTarget:self selector:@selector(displayLinkCallback)];
+}
+
+- (void)displayLinkCallback
+{
+    CFTimeInterval lastFrameTimestamp = self.displayLinkWrapper.timestamp;
+
+    if (self.previousFrameTimestamp == SentryPreviousFrameInitalValue) {
+        self.previousFrameTimestamp = lastFrameTimestamp;
+        return;
+    }
+
+    CFTimeInterval frameDuration = lastFrameTimestamp - self.previousFrameTimestamp;
+    self.previousFrameTimestamp = lastFrameTimestamp;
+
+    if (frameDuration > self.slowFrameThreshold && frameDuration <= SentryFrozenFrameThreshold) {
+        atomic_fetch_add_explicit(&_slowFrames, 1, SentryFramesMemoryOrder);
+    }
+
+    if (frameDuration > SentryFrozenFrameThreshold) {
+        atomic_fetch_add_explicit(&_frozenFrames, 1, SentryFramesMemoryOrder);
+    }
+
+    atomic_fetch_add_explicit(&_totalFrames, 1, SentryFramesMemoryOrder);
+}
+
+- (NSUInteger)currentTotalFrames
+{
+    return atomic_load_explicit(&_totalFrames, SentryFramesMemoryOrder);
+}
+
+- (NSUInteger)currentSlowFrames
+{
+    return atomic_load_explicit(&_slowFrames, SentryFramesMemoryOrder);
+}
+
+- (NSUInteger)currentFrozenFrames
+{
+    return atomic_load_explicit(&_frozenFrames, SentryFramesMemoryOrder);
+}
+
+- (void)stop
+{
+    _isRunning = NO;
+    [self.displayLinkWrapper invalidate];
+}
+
+@end
+
+#endif

Sources/Sentry/SentryFramesTrackingIntegration.m

@@ -0,0 +1,51 @@
+#import "SentryFramesTrackingIntegration.h"
+#import "SentryDisplayLinkWrapper.h"
+#import "SentryFramesTracker.h"
+#import "SentryLog.h"
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface
+SentryFramesTrackingIntegration ()
+
+#if SENTRY_HAS_UIKIT
+@property (nonatomic, strong) SentryFramesTracker *tracker;
+#endif
+
+@end
+
+@implementation SentryFramesTrackingIntegration
+
+- (void)installWithOptions:(SentryOptions *)options
+{
+#if SENTRY_HAS_UIKIT
+    if (options.enableFrameRenderMeasuring) {
+        self.tracker = [SentryFramesTracker sharedInstance];
+        [self.tracker start];
+    }
+#else
+    [SentryLog
+        logWithMessage:
+            @"NO UIKit -> SentryFramesTrackingIntegration will not track slow and frozen frames."
+              andLevel:kSentryLevelInfo];
+#endif
+}
+
+- (void)uninstall
+{
+    [self stop];
+}
+
+- (void)stop
+{
+#if SENTRY_HAS_UIKIT
+    if (nil != self.tracker) {
+        [self.tracker stop];
+    }
+#endif
+}
+
+@end
+
+NS_ASSUME_NONNULL_END

Sources/Sentry/SentryOptions.m

@@ -19,9 +19,10 @@ @implementation SentryOptions
 + (NSArray<NSString *> *)defaultIntegrations
 {
     return @[
-        @"SentryCrashIntegration", @"SentryAutoBreadcrumbTrackingIntegration",
-        @"SentryAutoSessionTrackingIntegration", @"SentryAppStartTrackingIntegration",
-        @"SentryOutOfMemoryTrackingIntegration", @"SentryPerformanceTrackingIntegration"
+        @"SentryCrashIntegration", @"SentryFramesTrackingIntegration",
+        @"SentryAutoBreadcrumbTrackingIntegration", @"SentryAutoSessionTrackingIntegration",
+        @"SentryAppStartTrackingIntegration", @"SentryOutOfMemoryTrackingIntegration",
+        @"SentryPerformanceTrackingIntegration"
     ];
 }
 
@@ -39,6 +40,7 @@ - (instancetype)init
         self.enableAutoSessionTracking = YES;
         self.enableOutOfMemoryTracking = YES;
         self.enableAppStartMeasuring = YES;
+        self.enableFrameRenderMeasuring = YES;
         self.sessionTrackingIntervalMillis = [@30000 unsignedIntValue];
         self.attachStacktrace = YES;
         self.maxAttachmentSize = 20 * 1024 * 1024;
@@ -192,6 +194,10 @@ - (void)validateOptions:(NSDictionary<NSString *, id> *)options
         self.enableAppStartMeasuring = [options[@"enableAppStartMeasuring"] boolValue];
     }
 
+    if (nil != options[@"enableFrameRenderMeasuring"]) {
+        self.enableFrameRenderMeasuring = [options[@"enableFrameRenderMeasuring"] boolValue];
+    }
+
     if (nil != options[@"sessionTrackingIntervalMillis"]) {
         self.sessionTrackingIntervalMillis =
             [options[@"sessionTrackingIntervalMillis"] unsignedIntValue];

Sources/Sentry/SentryTracer.m

@@ -1,6 +1,8 @@
 #import "SentryTracer.h"
 #import "SentryAppStartMeasurement.h"
+#import "SentryFramesTracker.h"
 #import "SentryHub.h"
+#import "SentryLog.h"
 #import "SentrySDK+Private.h"
 #import "SentryScope.h"
 #import "SentrySpan.h"
@@ -32,6 +34,14 @@
 
 @implementation SentryTracer {
     BOOL _waitForChildren;
+
+#if SENTRY_HAS_UIKIT
+    BOOL _startTimeChanged;
+
+    NSUInteger initTotalFrames;
+    NSUInteger initSlowFrames;
+    NSUInteger initFrozenFrames;
+#endif
 }
 
 - (instancetype)initWithTransactionContext:(SentryTransactionContext *)transactionContext
@@ -52,6 +62,19 @@ - (instancetype)initWithTransactionContext:(SentryTransactionContext *)transacti
         self.isWaitingForChildren = NO;
         _waitForChildren = waitForChildren;
         self.finishStatus = kSentrySpanStatusUndefined;
+
+#if SENTRY_HAS_UIKIT
+        _startTimeChanged = NO;
+
+        // Store current amount of frames at the beginning to be able to calculate the amount of
+        // frames at the end of the transaction.
+        SentryFramesTracker *framesTracker = [SentryFramesTracker sharedInstance];
+        if (framesTracker.isRunning) {
+            initTotalFrames = framesTracker.currentTotalFrames;
+            initSlowFrames = framesTracker.currentSlowFrames;
+            initFrozenFrames = framesTracker.currentFrozenFrames;
+        }
+#endif
     }
 
     return self;
@@ -139,6 +162,10 @@ - (NSDate *)startTimestamp
 - (void)setStartTimestamp:(NSDate *)startTimestamp
 {
     self.rootSpan.startTimestamp = startTimestamp;
+
+#if SENTRY_HAS_UIKIT
+    _startTimeChanged = YES;
+#endif
 }
 
 - (NSDictionary<NSString *, id> *)data
@@ -313,6 +340,8 @@ - (nullable SentryAppStartMeasurement *)getAppStartMeasurement
 - (void)addMeasurements:(SentryTransaction *)transaction
     appStartMeasurement:(nullable SentryAppStartMeasurement *)appStartMeasurement
 {
+    NSString *valueKey = @"value";
+
     if (appStartMeasurement != nil && appStartMeasurement.type != SentryAppStartTypeUnknown) {
         NSString *type = nil;
         if (appStartMeasurement.type == SentryAppStartTypeCold) {
@@ -322,10 +351,32 @@ - (void)addMeasurements:(SentryTransaction *)transaction
         }
 
         if (type != nil) {
-            [transaction setMeasurementValue:@{ @"value" : @(appStartMeasurement.duration * 1000) }
+            [transaction setMeasurementValue:@{ valueKey : @(appStartMeasurement.duration * 1000) }
                                       forKey:type];
         }
     }
+
+#if SENTRY_HAS_UIKIT
+    // Frames
+    SentryFramesTracker *framesTracker = [SentryFramesTracker sharedInstance];
+    if (framesTracker.isRunning && !_startTimeChanged) {
+        NSInteger totalFrames = framesTracker.currentTotalFrames - initTotalFrames;
+        NSInteger slowFrames = framesTracker.currentSlowFrames - initSlowFrames;
+        NSInteger frozenFrames = framesTracker.currentFrozenFrames - initFrozenFrames;
+
+        if (totalFrames >= 0 && slowFrames >= 0 && frozenFrames >= 0) {
+            [transaction setMeasurementValue:@{ valueKey : @(totalFrames) } forKey:@"frames_total"];
+            [transaction setMeasurementValue:@{ valueKey : @(slowFrames) } forKey:@"frames_slow"];
+            [transaction setMeasurementValue:@{ valueKey : @(frozenFrames) }
+                                      forKey:@"frames_frozen"];
+
+            NSString *message = [NSString
+                stringWithFormat:@"Frames for transaction \"%@\" Total:%ld Slow:%ld Frozen:%ld",
+                self.context.operation, (long)totalFrames, (long)slowFrames, (long)frozenFrames];
+            [SentryLog logWithMessage:message andLevel:kSentryLevelDebug];
+        }
+    }
+#endif
 }
 
 - (id<SentrySpan>)buildSpan:(SentrySpanId *)parentId

Sources/Sentry/include/SentryDisplayLinkWrapper.h

@@ -0,0 +1,22 @@
+#import "SentryDefines.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+#if SENTRY_HAS_UIKIT
+
+/**
+ * A wrapper around DisplayLink for testability.
+ */
+@interface SentryDisplayLinkWrapper : NSObject
+
+@property (readonly, nonatomic) CFTimeInterval timestamp;
+
+- (void)linkWithTarget:(id)target selector:(SEL)sel;
+
+- (void)invalidate;
+
+@end
+
+#endif
+
+NS_ASSUME_NONNULL_END