@react-native-firebase/perf 16.6.0 → 16.7.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [16.7.0](https://github.com/invertase/react-native-firebase/compare/v16.6.0...v16.7.0) (2023-01-28)
+
+### Features
+
+- **perf:** add custom screen rendering traces for android ([#6588](https://github.com/invertase/react-native-firebase/issues/6588)) ([9f2498d](https://github.com/invertase/react-native-firebase/commit/9f2498d29ee3780cba5a7a69fde8f7c370ad723b))
+
 ## [16.6.0](https://github.com/invertase/react-native-firebase/compare/v16.5.2...v16.6.0) (2023-01-27)
 
 **Note:** Version bump only for package @react-native-firebase/perf

package/android/src/main/java/io/invertase/firebase/perf/ScreenTrace.java

@@ -0,0 +1,207 @@
+package io.invertase.firebase.perf;
+
+/**
+ * Copyright 2021 Google Inc. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import android.app.Activity;
+import android.os.Build;
+import android.util.Log;
+import android.util.SparseIntArray;
+import android.view.WindowManager;
+
+import androidx.core.app.FrameMetricsAggregator;
+
+import com.google.firebase.perf.FirebasePerformance;
+import com.google.firebase.perf.metrics.Trace;
+import com.google.firebase.perf.util.Constants;
+
+/**
+ * Utility class to capture Screen rendering information (Slow/Frozen frames) for the
+ * {@code Activity} passed to the constructor {@link io.invertase.firebase.perf.ScreenTrace#ScreenTrace(Activity, String)}.
+ * <p>
+ * Learn more at https://firebase.google.com/docs/perf-mon/screen-traces?platform=android.
+ * <p>
+ * A slow screen rendering often leads to a UI Jank which creates a bad user experience. Below are
+ * some tips and references to understand and fix common UI Jank issues:
+ * - https://developer.android.com/topic/performance/vitals/render.html#fixing_jank
+ * - https://youtu.be/CaMTIgxCSqU (Why 60fps?)
+ * - https://youtu.be/HXQhu6qfTVU (Rendering Performance)
+ * - https://youtu.be/1iaHxmfZGGc (Understanding VSYNC)
+ * - https://www.youtube.com/playlist?list=PLOU2XLYxmsIKEOXh5TwZEv89aofHzNCiu (Android Performance Patterns)
+ * <p>
+ * References:
+ * - Fireperf Source Code
+ */
+public class ScreenTrace {
+
+  private static final String TAG = "RNFirebasePerf";
+  private static final String FRAME_METRICS_AGGREGATOR_CLASSNAME =
+    "androidx.core.app.FrameMetricsAggregator";
+
+  private final Activity activity;
+  private final String traceName;
+
+  private final FrameMetricsAggregator frameMetricsAggregator;
+  private Trace perfScreenTrace;
+
+  /**
+   * Default constructor for this class.
+   *
+   * @param activity for which the screen traces should be recorded.
+   * @param tag      used as an identifier for the name to be used to log screen rendering
+   *                 information (like "MyFancyScreen").
+   * @implNote It requires hardware acceleration to be on or it throws.
+   */
+  public ScreenTrace(Activity activity, String tag) throws IllegalStateException {
+    this.activity = activity;
+
+    // We don't care about adding the activity name to the trace name
+    // because RN doesn't care about activities
+    this.traceName = tag;
+
+    boolean isScreenTraceSupported = checkScreenTraceSupport(activity);
+
+    if (!isScreenTraceSupported) {
+      throw new IllegalStateException("Device does not support screen traces. Hardware acceleration must be enabled and Android must not be 8.0 or 8.1.");
+    }
+
+    frameMetricsAggregator = new FrameMetricsAggregator();
+  }
+
+  // region Public APIs
+
+  /**
+   * Starts recording the frame metrics for the screen traces.
+   */
+  public void recordScreenTrace() {
+    Log.d(TAG, "Recording screen trace " + traceName);
+
+    frameMetricsAggregator.add(activity);
+    perfScreenTrace = FirebasePerformance.startTrace(getScreenTraceName());
+  }
+
+  /**
+   * Stops recording screen traces and dispatches the trace capturing information on %age of
+   * Slow/Frozen frames.
+   *
+   * Inspired by fireperf source.
+   */
+  public void sendScreenTrace() {
+    if (perfScreenTrace == null) return;
+
+    int totalFrames = 0;
+    int slowFrames = 0;
+    int frozenFrames = 0;
+
+    // Stops recording metrics for this Activity and returns the currently-collected metrics
+    SparseIntArray[] arr = frameMetricsAggregator.reset();
+
+    if (arr != null) {
+      SparseIntArray frameTimes = arr[FrameMetricsAggregator.TOTAL_INDEX];
+
+      if (frameTimes != null) {
+        for (int i = 0; i < frameTimes.size(); i++) {
+          int frameTime = frameTimes.keyAt(i);
+          int numFrames = frameTimes.valueAt(i);
+
+          totalFrames += numFrames;
+
+          if (frameTime > Constants.FROZEN_FRAME_TIME) {
+            // Frozen frames mean the app appear frozen. The recommended thresholds is 700ms
+            frozenFrames += numFrames;
+          }
+
+          if (frameTime > Constants.SLOW_FRAME_TIME) {
+            // Slow frames are anything above 16ms (i.e. 60 frames/second)
+            slowFrames += numFrames;
+          }
+        }
+      }
+    }
+
+    // Only incrementMetric if corresponding metric is non-zero.
+    if (totalFrames > 0) {
+      perfScreenTrace.putMetric(Constants.CounterNames.FRAMES_TOTAL.toString(), totalFrames);
+    }
+    if (slowFrames > 0) {
+      perfScreenTrace.putMetric(Constants.CounterNames.FRAMES_SLOW.toString(), slowFrames);
+    }
+    if (frozenFrames > 0) {
+      perfScreenTrace.putMetric(Constants.CounterNames.FRAMES_FROZEN.toString(), frozenFrames);
+    }
+
+    Log.d(TAG, new StringBuilder()
+      .append("sendScreenTrace ").append(traceName)
+      .append(", name: ").append(getScreenTraceName())
+      .append(", total_frames: ").append(totalFrames)
+      .append(", slow_frames: ").append(slowFrames)
+      .append(", frozen_frames: ").append(frozenFrames).toString());
+
+    // Stop and record trace
+    perfScreenTrace.stop();
+  }
+
+  // endregion
+
+  // region Helper Functions
+
+  private static boolean checkScreenTraceSupport(Activity activity) {
+    boolean isValidSDKVersion = checkSDKVersion();
+    boolean hasFrameMetricsAggregatorClass = checkFrameMetricsAggregatorClass();
+    boolean isActivityHardwareAccelerated = activity.getWindow() != null
+      && ((activity.getWindow().getAttributes().flags & WindowManager.LayoutParams.FLAG_HARDWARE_ACCELERATED) != 0);
+
+
+    boolean supported = isValidSDKVersion && hasFrameMetricsAggregatorClass && isActivityHardwareAccelerated;
+
+    Log.d(TAG, new StringBuilder()
+      .append("isValidSDKVersion: ").append(isValidSDKVersion)
+      .append("isScreenTraceSupported(").append(activity).append("): ").append(supported)
+      .append(" [hasFrameMetricsAggregatorClass: ").append(hasFrameMetricsAggregatorClass)
+      .append(", isActivityHardwareAccelerated: ").append(isActivityHardwareAccelerated).append("]").toString());
+
+    return supported;
+  }
+
+  private static boolean checkSDKVersion() {
+    if (Build.VERSION.SDK_INT == 26 || Build.VERSION.SDK_INT == 27) {
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+   * Inspired by fireperf source.
+   */
+  private static boolean checkFrameMetricsAggregatorClass() {
+    try {
+      Class<?> initializerClass = Class.forName(FRAME_METRICS_AGGREGATOR_CLASSNAME);
+      return true;
+    } catch (ClassNotFoundException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Inspired by fireperf source.
+   */
+  private String getScreenTraceName() {
+    return Constants.SCREEN_TRACE_PREFIX + traceName;
+  }
+
+  // endregion
+}

package/android/src/main/java/io/invertase/firebase/perf/UniversalFirebasePerfModule.java

@@ -17,6 +17,7 @@ package io.invertase.firebase.perf;
  *
  */
 
+import android.app.Activity;
 import android.content.Context;
 import android.os.Bundle;
 import android.util.SparseArray;
@@ -33,6 +34,7 @@ import java.util.Set;
 
 public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
   private static SparseArray<Trace> traces = new SparseArray<>();
+  private static SparseArray<ScreenTrace> screenTraces = new SparseArray<>();
   private static SparseArray<HttpMetric> httpMetrics = new SparseArray<>();
 
   UniversalFirebasePerfModule(Context context, String serviceName) {
@@ -44,6 +46,7 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
     super.onTearDown();
     traces.clear();
     httpMetrics.clear();
+    screenTraces.clear();
   }
 
   @Override
@@ -100,6 +103,28 @@ public class UniversalFirebasePerfModule extends UniversalFirebaseModule {
         });
   }
 
+  Task<Void> startScreenTrace(Activity activity, int id, String identifier) {
+    return Tasks.call(
+      () -> {
+        ScreenTrace screenTrace = new ScreenTrace(activity, identifier);
+        screenTrace.recordScreenTrace();
+        screenTraces.put(id, screenTrace);
+
+        return null;
+      });
+  }
+
+  Task<Void> stopScreenTrace(int id) {
+    return Tasks.call(
+      () -> {
+        ScreenTrace trace = screenTraces.get(id);
+        trace.sendScreenTrace();
+        screenTraces.remove(id);
+
+        return null;
+      });
+  }
+
   Task<Void> startHttpMetric(int id, String url, String httpMethod) {
     return Tasks.call(
         () -> {

package/android/src/reactnative/java/io/invertase/firebase/perf/ReactNativeFirebasePerfModule.java

@@ -17,6 +17,7 @@ package io.invertase.firebase.perf;
  *
  */
 
+import android.app.Activity;
 import com.facebook.react.bridge.Arguments;
 import com.facebook.react.bridge.Promise;
 import com.facebook.react.bridge.ReactApplicationContext;
@@ -85,6 +86,42 @@ public class ReactNativeFirebasePerfModule extends ReactNativeFirebaseModule {
             });
   }
 
+  @ReactMethod
+  public void startScreenTrace(int id, String identifier, Promise promise) {
+    Activity currentActivity = getCurrentActivity();
+
+    // protect against NPEs
+    if (currentActivity == null) {
+      promise.resolve(null);
+      return;
+    }
+
+    module
+      .startScreenTrace(currentActivity, id, identifier)
+      .addOnCompleteListener(
+        task -> {
+          if (task.isSuccessful()) {
+            promise.resolve(task.getResult());
+          } else {
+            rejectPromiseWithExceptionMap(promise, task.getException());
+          }
+        });
+  }
+
+  @ReactMethod
+  public void stopScreenTrace(int id, Promise promise) {
+    module
+      .stopScreenTrace(id)
+      .addOnCompleteListener(
+        task -> {
+          if (task.isSuccessful()) {
+            promise.resolve(task.getResult());
+          } else {
+            rejectPromiseWithExceptionMap(promise, task.getException());
+          }
+        });
+  }
+
   @ReactMethod
   public void startHttpMetric(int id, String url, String httpMethod, Promise promise) {
     module

package/lib/ScreenTrace.js

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2016-present Invertase Limited & Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this library except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ */
+
+import { isIOS } from '@react-native-firebase/app/lib/common';
+
+let id = 0;
+
+export default class ScreenTrace {
+  constructor(native, identifier) {
+    this.native = native;
+    this._identifier = identifier;
+    this._id = id++;
+    this._started = false;
+    this._stopped = false;
+  }
+
+  start() {
+    if (isIOS) {
+      return Promise.reject(new Error('Custom screentraces are currently not supported on iOS.'));
+    }
+    if (this._started) {
+      return Promise.resolve(null);
+    }
+    this._started = true;
+
+    return this.native.startScreenTrace(this._id, this._identifier);
+  }
+
+  stop() {
+    if (!this._started || this._stopped) {
+      return Promise.resolve(null);
+    }
+    this._stopped = true;
+
+    return this.native.stopScreenTrace(this._id);
+  }
+}

package/lib/index.d.ts

@@ -211,6 +211,48 @@ export namespace FirebasePerformanceTypes {
     stop(): Promise<null>;
   }
 
+  /**
+   * ScreenTrace allows you to record a custom screen rendering trace of slow and frozen frames.
+   * Throws on constructor if hardware acceleration is off or if Android is 9.0 or 9.1.
+   *
+   * @platform android Android !== 9.0.0 && Adnroid !== 9.1.0
+   */
+  export class ScreenTrace {
+    /**
+     * Starts a new screen trace. Does nothing if already started.
+     *
+     * #### Example
+     *
+     * ```js
+     * try {
+     *   const trace = firebase.perf().newScreenTrace('FooScreen');
+     *   await trace.start();
+     * } catch (e) {
+     *
+     * }
+     * ```
+     * @platform android Android >= 9.0.0
+     */
+    start(): Promise<null>;
+    /**
+     * Stops and sends the screen trace.
+     *
+     * #### Example
+     *
+     * ```js
+     * try {
+     *   const trace = firebase.perf().newScreenTrace('FooScreen');
+     *   await trace.start();
+     *   await trace.stop();
+     * } catch (e) {
+     *
+     * }
+     * ```
+     * @platform android Android >= 9.0.0
+     */
+    stop(): Promise<null>;
+  }
+
   /**
    * Metric used to collect data for network requests/responses. A new instance must be used for every request/response.
    */
@@ -426,6 +468,45 @@ export namespace FirebasePerformanceTypes {
      */
     startTrace(identifier: string): Promise<Trace>;
 
+    /**
+     * Creates a ScreenTrace instance with the given identifier.
+     * Throws if hardware acceleration is diabled or if Android is 9.0 or 9.1.
+     *
+     * #### Example
+     *
+     * ```js
+     * try {
+     *   const trace = firebase.perf().newScreenTrace('FooScreen');
+     *   await trace.start();
+     * } catch (e) {
+     *
+     * }
+     * ```
+     *
+     * @param identifier Name of the trace, no leading or trailing whitespace allowed, no leading underscore '_' character allowed, max length is 100.
+     */
+    newScreenTrace(identifier: string): ScreenTrace;
+
+    /**
+     * Creates a ScreenTrace instance with the given identifier and immediately starts it.
+     * Throws if hardware acceleration is diabled or if Android is 9.0 or 9.1.
+     *
+     * #### Example
+     *
+     * ```js
+     * try {
+     *   const trace = await firebase.perf().startScreenTrace('FooScreen');
+     *   await trace.stop();
+     * } catch (e) {
+     *
+     * }
+     * ```
+     * @platform android Android !== 9.0.0 && Android !== 9.1.0
+     *
+     * @param identifier Name of the screen
+     */
+    startScreenTrace(identifier: string): Promise<ScreenTrace>;
+
     /**
      * Creates a HttpMetric instance for collecting network performance data for a single request/response
      *

package/lib/index.js

@@ -23,6 +23,7 @@ import {
 } from '@react-native-firebase/app/lib/internal';
 import HttpMetric from './HttpMetric';
 import Trace from './Trace';
+import ScreenTrace from './ScreenTrace';
 import version from './version';
 
 const statics = {};
@@ -80,6 +81,21 @@ class FirebasePerfModule extends FirebaseModule {
     return trace.start().then(() => trace);
   }
 
+  newScreenTrace(identifier) {
+    if (!isString(identifier) || identifier.length > 100) {
+      throw new Error(
+        "firebase.perf().newScreenTrace(*) 'identifier' must be a string with a maximum length of 100 characters.",
+      );
+    }
+
+    return new ScreenTrace(this.native, identifier);
+  }
+
+  startScreenTrace(identifier) {
+    const screenTrace = this.newScreenTrace(identifier);
+    return screenTrace.start().then(() => screenTrace);
+  }
+
   newHttpMetric(url, httpMethod) {
     if (!isString(url)) {
       throw new Error("firebase.perf().newHttpMetric(*, _) 'url' must be a string.");

package/lib/version.js

@@ -1,2 +1,2 @@
 // Generated by genversion.
-module.exports = '16.6.0';
+module.exports = '16.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-native-firebase/perf",
-  "version": "16.6.0",
+  "version": "16.7.0",
   "author": "Invertase <oss@invertase.io> (http://invertase.io)",
   "description": "React Native Firebase - React Native Firebase provides native integration with Performance Monitoring to gain insight into key performance characteristics within your React Native application.",
   "main": "lib/index.js",
@@ -29,7 +29,7 @@
     "performance monitoring"
   ],
   "peerDependencies": {
-    "@react-native-firebase/app": "16.6.0"
+    "@react-native-firebase/app": "16.7.0"
   },
   "dependencies": {
     "@expo/config-plugins": "^5.0.4"
@@ -37,5 +37,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6663dc24dc5697190b930aa510085a681fe81203"
+  "gitHead": "a94f371da16f9bf873c18b09541cbeb19960978d"
 }