react-native-nitro-tracing 0.6.0

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+## 0.6.0
+
+First public release. In-app performance tracing for React Native, for development, custom and UAT builds.
+
+### Features
+
+- **native:** bounded C++ recorder with a monotonic clock, explicit parent IDs, and source span IDs that link parents completing after their children.
+- **native:** native sampler thread for UI fps, max frame gap, slow and frozen frames (CADisplayLink / Choreographer), process CPU and memory.
+- **native:** `Recording.exportTraceEvents()` writes Chrome Trace Event / Perfetto JSON: a lane per source, instants for marks, and counters for metrics.
+- **native:** metric samples may use at most half of the buffer and roll over within it, so long sessions keep their spans. Only lost spans and marks count as dropped history.
+- **native:** stats split lost history by kind (`droppedSpans`, `droppedMarks`, `droppedMetrics`). The inspector says "Lost 12 spans, 3 marks" instead of a bare count.
+- **client:** `createTraceClient` owns the recording lifecycle, plugins, the `trace` facade (`mark`, `metric`, `measure`, `measureSince`) and sharing.
+- **client:** `shareTrace('perfetto')` shares a trace without stopping the recording.
+- **client:** `flag(note?)` marks a problem and captures a bounded Hermes CPU profile (`flagProfileMs`, default 10 s). The profile is linked from the export.
+- **client:** keeps 10000 events / 6 MB by default for multi-hour UAT sessions.
+- **plugins:** collectors for native metrics, navigation and screens (`createScreenTracker` for custom tabs), network (XHR and native fetch), JS errors, runtime metrics and the Performance API.
+- **plugins:** Sentry as an alternative measurement layer: frames and app start map onto the same metric names. Optional span export.
+- **inspector:**
+  - Summary triages issues by topic: startup, screens, network, responsiveness, resources, errors.
+  - Timeline groups events by screen visit.
+  - Explore has search, sort and draft filters, with trace waterfalls.
+  - Metrics carry units.
+- **inspector:** native tab bar with Liquid Glass and native menus on iOS; React Native fallbacks elsewhere. Labels are localizable in the package.
+- **inspector:** live overlay with a draggable FPS bubble, a non-modal sheet for the current screen, and Flag and Share buttons.
+- **example:** Instruments-style activity generators for screens, network, stalls and errors.
+
+### Bug Fixes
+
+- **native:** stopping a CPU profile really stops Hermes sampling on Android. React Native 0.85 binds `HermesSamplingProfiler.disable()` to the native enable, so `react-native-release-profiler`'s stop restarted the sampler. It then ran until the process died, and a dev reload aborted the app. `Tracing.disableHermesSampling()` stops it through the Hermes C++ API after every stop, and a ReactHost before-destroy guard stops it before reloads.
+- **native:** armeabi-v7a builds compile (size_t narrowing).
+- **inspector:** lists key rows by event sequence, so collectors that reuse a span ID cannot corrupt them.
+- **inspector:** Android no longer crashes on AppCompat hosts: native tabs are iOS-only.
+
+### Documentation
+
+- Guides for getting started, collectors, inspector and overlay, exporting, native API, architecture, troubleshooting and releasing.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gugell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NitroTracing.podspec

@@ -0,0 +1,32 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "NitroTracing"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported, :visionos => 1.0 }
+  s.source       = { :http => "https://registry.npmjs.org/#{package["name"]}/-/#{package["name"]}-#{s.version}.tgz" }
+
+  s.source_files = [
+    # Implementation (Swift)
+    "ios/**/*.{swift}",
+    # Autolinking/Registration (Objective-C++)
+    "ios/**/*.{m,mm}",
+    # Implementation (C++ objects)
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  load 'nitrogen/generated/ios/NitroTracing+autolinking.rb'
+  add_nitrogen_files(s)
+
+  s.frameworks = 'QuartzCore'
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+  install_modules_dependencies(s)
+end

package/README.md

@@ -0,0 +1,75 @@
+# react-native-nitro-tracing
+
+In-app performance tracing for React Native, for development, custom and UAT builds. It records spans, marks and metrics into a bounded C++ recorder. Native collectors measure frames, CPU and memory, and a live inspector runs inside the app. Recordings export to [Perfetto](https://ui.perfetto.dev).
+
+Requires the New Architecture, Hermes and [`react-native-nitro-modules`](https://nitro.margelo.com) ^0.37.1, in a development or native build. Expo Go cannot load it.
+
+```sh
+npx expo install react-native-nitro-tracing react-native-nitro-modules
+# inspector and overlay:
+npx expo install react-native-safe-area-context @legendapp/list
+```
+
+```ts
+import { createTraceClient } from 'react-native-nitro-tracing/client'
+import { createExpoTraceSharing } from 'react-native-nitro-tracing/expo'
+import {
+  createErrorsPlugin,
+  createNativeMetricsPlugin,
+  createNavigationPlugin,
+  createNetworkPlugin,
+} from 'react-native-nitro-tracing/plugins'
+
+export const tracing = createTraceClient({
+  ...createExpoTraceSharing(),
+  runtimeMetrics: true,
+  plugins: [
+    createNativeMetricsPlugin(),
+    createNavigationPlugin(navigationRef),
+    createNetworkPlugin(),
+    createErrorsPlugin(),
+  ],
+})
+await tracing.start()
+```
+
+```tsx
+import { TraceInspector, TraceOverlay } from 'react-native-nitro-tracing/react'
+
+{
+  showTracing && (
+    <>
+      <TraceOverlay client={tracing} />
+      <TraceInspector client={tracing} />
+    </>
+  )
+}
+```
+
+The package never gates itself on `__DEV__`; the app decides which builds include it. Tap **Flag** when something feels slow: it marks the moment and captures a CPU profile. **Share trace** sends a Perfetto file without stopping the recording.
+
+## Entry points
+
+| Import                                        | Contains                                                                    | Peers                                                                                                         |
+| --------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `react-native-nitro-tracing`                  | Native `Tracing` API                                                        | `react-native-nitro-modules`                                                                                  |
+| `react-native-nitro-tracing/client`           | `createTraceClient`: lifecycle, `trace` facade, share, flag                 | —                                                                                                             |
+| `react-native-nitro-tracing/plugins`          | Native metrics, navigation, network, errors, runtime metrics, `TracePlugin` | —                                                                                                             |
+| `react-native-nitro-tracing/react`            | `TraceInspector`, `TraceOverlay`, `useAppReadyMetric`, `defaultLabels`      | `react-native-safe-area-context`, `@legendapp/list`; optional `react-native-bottom-tabs`, `expo-glass-effect` |
+| `react-native-nitro-tracing/expo`             | Share sheet adapter, dev menu item                                          | `expo-file-system`, `expo-sharing`, `expo-dev-client`                                                         |
+| `react-native-nitro-tracing/performance`      | Performance API marks and measures                                          | optional `react-native-performance`                                                                           |
+| `react-native-nitro-tracing/sentry`           | Sentry as a measurement layer, and span export                              | `@sentry/react-native`                                                                                        |
+| `react-native-nitro-tracing/release-profiler` | Hermes CPU profiles for Flag and Tools                                      | `react-native-release-profiler`                                                                               |
+
+## Documentation
+
+[Getting started](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/getting-started.md) ·
+[Collectors](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/collectors.md) ·
+[Inspector and overlay](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/inspector.md) ·
+[Exporting traces](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/exporting.md) ·
+[Native API](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/native-api.md) ·
+[Architecture](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/architecture.md) ·
+[Troubleshooting](https://github.com/gugell/react-native-nitro-tracing/blob/main/docs/troubleshooting.md) ·
+[Changelog](https://github.com/gugell/react-native-nitro-tracing/blob/main/packages/react-native-nitro-tracing/CHANGELOG.md)
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,49 @@
+project(NitroTracing)
+cmake_minimum_required(VERSION 3.9.0)
+
+set (PACKAGE_NAME NitroTracing)
+set (CMAKE_VERBOSE_MAKEFILE ON)
+set (CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED
+        src/main/cpp/cpp-adapter.cpp
+        ../cpp/HybridTracing.cpp
+        ../cpp/HybridRecording.cpp
+        ../cpp/HybridTraceSpan.cpp
+        ../cpp/HermesSampling.cpp
+        ../cpp/NativeConversions.cpp
+        ../cpp/core/Recorder.cpp
+        ../cpp/core/Retention.cpp
+        ../cpp/core/TraceJson.cpp
+        ../cpp/core/NativeSampler.cpp
+)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroTracing+autolinking.cmake)
+
+# Set up local includes
+include_directories(
+        "src/main/cpp"
+        "../cpp"
+)
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android                                   # <-- Android core
+)
+
+# Hermes C++ API, to stop the sampling profiler correctly (see cpp/HermesSampling.cpp).
+# Optional: without Hermes the library builds and disableHermesSampling() returns false.
+find_package(hermes-engine CONFIG)
+if(TARGET hermes-engine::hermesvm)
+  target_link_libraries(${PACKAGE_NAME} hermes-engine::hermesvm)
+  target_compile_definitions(${PACKAGE_NAME} PRIVATE NITRO_TRACING_HERMES=1)
+elseif(TARGET hermes-engine::libhermes)
+  target_link_libraries(${PACKAGE_NAME} hermes-engine::libhermes)
+  target_compile_definitions(${PACKAGE_NAME} PRIVATE NITRO_TRACING_HERMES=1)
+endif()

package/android/build.gradle

@@ -0,0 +1,133 @@
+buildscript {
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:9.2.1"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+def isNewArchitectureEnabled() {
+  return rootProject.hasProperty("newArchEnabled") && rootProject.getProperty("newArchEnabled") == "true"
+}
+
+apply plugin: "com.android.library"
+apply plugin: 'org.jetbrains.kotlin.android'
+apply from: '../nitrogen/generated/android/NitroTracing+autolinking.gradle'
+apply from: "./fix-prefab.gradle"
+
+def getExtOrDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : project.properties["NitroTracing_" + name]
+}
+
+def getExtOrIntegerDefault(name) {
+  return rootProject.ext.has(name) ? rootProject.ext.get(name) : (project.properties["NitroTracing_" + name]).toInteger()
+}
+
+android {
+  namespace "com.margelo.nitro.nitrotracing"
+
+  ndkVersion getExtOrDefault("ndkVersion")
+  compileSdkVersion getExtOrIntegerDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrIntegerDefault("minSdkVersion")
+    targetSdkVersion getExtOrIntegerDefault("targetSdkVersion")
+    consumerProguardFiles "proguard-rules.pro"
+    buildConfigField "boolean", "IS_NEW_ARCHITECTURE_ENABLED", isNewArchitectureEnabled().toString()
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -Wextra -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+            "META-INF",
+            "META-INF/**",
+            "**/libc++_shared.so",
+            "**/libNitroModules.so",
+            "**/libfbjni.so",
+            "**/libjsi.so",
+            "**/libfolly_json.so",
+            "**/libfolly_runtime.so",
+            "**/libglog.so",
+            "**/libhermes.so",
+            "**/libhermesvm.so",
+            "**/libhermes-executor-debug.so",
+            "**/libhermes_executor.so",
+            "**/libreactnative.so",
+            "**/libreactnativejni.so",
+            "**/libturbomodulejsijni.so",
+            "**/libreact_nativemodule_core.so",
+            "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lintOptions {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+
+}
+
+repositories {
+  mavenCentral()
+  google()
+}
+
+
+dependencies {
+  // React Native is provided by the consuming app. Keeping this compileOnly
+  // prevents this library AAR from dexing RN classes a second time in release.
+  compileOnly "com.facebook.react:react-android"
+
+  // NitroModules is provided by the consuming app. Keeping this compileOnly
+  // avoids bundling NitroModules' runtime graph, including react-android, into
+  // this library AAR during release dexing.
+  compileOnly project(":react-native-nitro-modules")
+
+  // Hermes prefab headers and library, provided by the app at runtime.
+  compileOnly "com.facebook.react:hermes-android"
+}

package/android/fix-prefab.gradle

@@ -0,0 +1,51 @@
+tasks.configureEach { task ->
+  // Make sure that we generate our prefab publication file only after having built the native library
+  // so that not a header publication file, but a full configuration publication will be generated, which
+  // will include the .so file
+
+  def prefabConfigurePattern = ~/^prefab(.+)ConfigurePackage$/
+  def matcher = task.name =~ prefabConfigurePattern
+  if (matcher.matches()) {
+    def variantName = matcher[0][1]
+    task.outputs.upToDateWhen { false }
+    task.dependsOn("externalNativeBuild${variantName}")
+  }
+}
+
+afterEvaluate {
+  def abis = reactNativeArchitectures()
+  rootProject.allprojects.each { proj ->
+    if (proj === rootProject) return
+
+    def dependsOnThisLib = proj.configurations.findAll { it.canBeResolved }.any { config ->
+      config.dependencies.any { dep ->
+        dep.group == project.group && dep.name == project.name
+      }
+    }
+    if (!dependsOnThisLib && proj != project) return
+
+    if (!proj.plugins.hasPlugin('com.android.application') && !proj.plugins.hasPlugin('com.android.library')) {
+      return
+    }
+
+    def variants = proj.android.hasProperty('applicationVariants') ? proj.android.applicationVariants : proj.android.libraryVariants
+    // Touch the prefab_config.json files to ensure that in ExternalNativeJsonGenerator.kt we will re-trigger the prefab CLI to
+    // generate a libnameConfig.cmake file that will contain our native library (.so).
+    // See this condition: https://cs.android.com/android-studio/platform/tools/base/+/mirror-goog-studio-main:build-system/gradle-core/src/main/java/com/android/build/gradle/tasks/ExternalNativeJsonGenerator.kt;l=207-219?q=createPrefabBuildSystemGlue
+    variants.all { variant ->
+      def variantName = variant.name
+      abis.each { abi ->
+        def searchDir = new File(proj.projectDir, ".cxx/${variantName}")
+        if (!searchDir.exists()) return
+        def matches = []
+        searchDir.eachDir { randomDir ->
+          def prefabFile = new File(randomDir, "${abi}/prefab_config.json")
+          if (prefabFile.exists()) matches << prefabFile
+        }
+        matches.each { prefabConfig ->
+          prefabConfig.setLastModified(System.currentTimeMillis())
+        }
+      }
+    }
+  }
+}

package/android/gradle.properties

@@ -0,0 +1,5 @@
+NitroTracing_kotlinVersion=2.1.21
+NitroTracing_minSdkVersion=23
+NitroTracing_targetSdkVersion=36
+NitroTracing_compileSdkVersion=36
+NitroTracing_ndkVersion=29.0.14206865

package/android/proguard-rules.pro

@@ -0,0 +1,5 @@
+# Called only from C++ over JNI; keep it through R8 in release builds.
+-keep class com.margelo.nitro.nitrotracing.NitroTracingFrameSource { *; }
+# Reload guard: instantiated from ReactModuleInfo by class name; its JNI bridge is native.
+-keep class com.margelo.nitro.nitrotracing.HermesSamplingGuard { *; }
+-keep class com.margelo.nitro.nitrotracing.HermesSampling { *; }

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,47 @@
+#include "HermesSampling.hpp"
+#include "NitroTracingOnLoad.hpp"
+#include "core/NativeSampler.hpp"
+#include <fbjni/fbjni.h>
+#include <jni.h>
+
+using margelo::nitro::tracingcore::FrameMonitor;
+
+namespace {
+// Resolved on the loader thread: FindClass from other threads cannot see app classes.
+jclass frameSourceClass = nullptr;
+jmethodID setEnabled = nullptr;
+
+void registerFrameSource(JNIEnv *env) {
+  jclass local = env->FindClass("com/margelo/nitro/nitrotracing/NitroTracingFrameSource");
+  if (!local) {
+    env->ExceptionClear();
+    return; // Frame metrics are optional; CPU and memory sampling still work.
+  }
+  frameSourceClass = static_cast<jclass>(env->NewGlobalRef(local));
+  env->DeleteLocalRef(local);
+  setEnabled = env->GetStaticMethodID(frameSourceClass, "setEnabled", "(Z)V");
+  FrameMonitor::instance().setToggle([](bool enabled) {
+    JNIEnv *env = facebook::jni::Environment::ensureCurrentThreadIsAttached();
+    env->CallStaticVoidMethod(frameSourceClass, setEnabled, static_cast<jboolean>(enabled));
+    if (env->ExceptionCheck())
+      env->ExceptionClear();
+  });
+}
+} // namespace
+
+extern "C" JNIEXPORT void JNICALL
+Java_com_margelo_nitro_nitrotracing_NitroTracingFrameSource_nativeOnFrame(JNIEnv *, jclass, jlong frameTimeNanos) {
+  // Choreographer frame times share the monotonic clock; 0 lets the monitor infer the interval.
+  FrameMonitor::instance().onFrame(static_cast<double>(frameTimeNanos) / 1e9, 0);
+}
+
+extern "C" JNIEXPORT jboolean JNICALL Java_com_margelo_nitro_nitrotracing_HermesSampling_disable(JNIEnv *, jclass) {
+  return margelo::nitro::nitrotracing::disableHermesSampling() ? JNI_TRUE : JNI_FALSE;
+}
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM *vm, void *) {
+  return facebook::jni::initialize(vm, [] {
+    margelo::nitro::nitrotracing::registerAllNatives();
+    registerFrameSource(facebook::jni::Environment::current());
+  });
+}

package/android/src/main/java/com/margelo/nitro/nitrotracing/HermesSamplingGuard.kt

@@ -0,0 +1,43 @@
+package com.margelo.nitro.nitrotracing
+
+import com.facebook.react.ReactApplication
+import com.facebook.react.ReactHost
+import com.facebook.react.bridge.BaseJavaModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.turbomodule.core.interfaces.TurboModule
+import java.util.Collections
+import java.util.WeakHashMap
+
+/**
+ * Stops Hermes' sampling profiler before a reload tears down the JS runtime.
+ *
+ * The sampler is process-wide. If a reload destroys the JS thread while it samples, the
+ * sampler signals a dead thread and the app aborts (`invalid pthread_t` on `hermes-sampling`).
+ * React Native quits the JS thread before invalidating modules, so this registers a
+ * ReactHost before-destroy listener, which runs while the thread is still alive.
+ * Eagerly initialized; JS never calls it.
+ */
+internal class HermesSamplingGuard(context: ReactApplicationContext) :
+    BaseJavaModule(context), TurboModule {
+  init {
+    (context.applicationContext as? ReactApplication)?.reactHost?.let(::watch)
+  }
+
+  override fun getName() = NAME
+
+  companion object {
+    const val NAME = "NitroTracingHermesSamplingGuard"
+    // One listener per host; a new module instance is created on every reload.
+    private val watched = Collections.newSetFromMap(WeakHashMap<ReactHost, Boolean>())
+
+    private fun watch(host: ReactHost) {
+      synchronized(watched) { if (!watched.add(host)) return }
+      host.addBeforeDestroyListener { runCatching { HermesSampling.disable() } }
+    }
+  }
+}
+
+/** JNI bridge to cpp/HermesSampling.cpp. */
+internal object HermesSampling {
+  @JvmStatic external fun disable(): Boolean
+}

package/android/src/main/java/com/margelo/nitro/nitrotracing/NitroTracingFrameSource.kt

@@ -0,0 +1,36 @@
+package com.margelo.nitro.nitrotracing
+
+import android.os.Handler
+import android.os.Looper
+import android.view.Choreographer
+
+/**
+ * Main-thread Choreographer callbacks, started only while a native sampler needs frames.
+ * A callback delayed past its vsync means the main thread was busy; the C++ FrameMonitor
+ * infers the display interval from the shortest recent gap.
+ */
+object NitroTracingFrameSource : Choreographer.FrameCallback {
+  private val main = Handler(Looper.getMainLooper())
+  private var running = false
+
+  @JvmStatic
+  fun setEnabled(enabled: Boolean) {
+    main.post {
+      if (enabled && !running) {
+        running = true
+        Choreographer.getInstance().postFrameCallback(this)
+      } else if (!enabled && running) {
+        running = false
+        Choreographer.getInstance().removeFrameCallback(this)
+      }
+    }
+  }
+
+  override fun doFrame(frameTimeNanos: Long) {
+    if (!running) return
+    nativeOnFrame(frameTimeNanos)
+    Choreographer.getInstance().postFrameCallback(this)
+  }
+
+  @JvmStatic private external fun nativeOnFrame(frameTimeNanos: Long)
+}

package/android/src/main/java/com/margelo/nitro/nitrotracing/NitroTracingPackage.kt

@@ -0,0 +1,31 @@
+package com.margelo.nitro.nitrotracing
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfo
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class NitroTracingPackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
+        if (name == HermesSamplingGuard.NAME) HermesSamplingGuard(reactContext) else null
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider {
+        mapOf(
+            HermesSamplingGuard.NAME to ReactModuleInfo(
+                HermesSamplingGuard.NAME,
+                HermesSamplingGuard::class.java.name,
+                false, // canOverrideExistingModule
+                true, // needsEagerInit: registers the reload guard at startup
+                false, // isCxxModule
+                true, // isTurboModule
+            ),
+        )
+    }
+
+    companion object {
+        init {
+            NitroTracingOnLoad.initializeNative()
+        }
+    }
+}

package/client.ts

@@ -0,0 +1,15 @@
+export { createTraceClient } from './src/client/createTraceClient'
+export type {
+  TraceClient,
+  TraceClientOptions,
+  TraceClientSnapshot,
+  ClientAttributes,
+  TraceFormat,
+} from './src/client/createTraceClient'
+
+export type {
+  PlaygroundReport,
+  PlaygroundCheckId,
+} from './src/client/playground'
+
+export type { TracingEntry, TracingSink } from './src/client/TracingSink'

package/cpp/HermesSampling.cpp

@@ -0,0 +1,26 @@
+#include "HermesSampling.hpp"
+
+#if defined(NITRO_TRACING_HERMES)
+#include <hermes/hermes.h>
+#endif
+
+namespace margelo::nitro::nitrotracing {
+bool disableHermesSampling() noexcept {
+#if defined(NITRO_TRACING_HERMES)
+  // React Native 0.85's HermesSamplingProfiler binds its Java disable() to the native
+  // enable(), so on Android "stop profiling" leaves the sampler running. This is the call
+  // the binding should have made.
+  try {
+    auto *api = facebook::jsi::castInterface<facebook::hermes::IHermesRootAPI>(facebook::hermes::makeHermesRootAPI());
+    if (api == nullptr)
+      return false;
+    api->disableSamplingProfiler();
+    return true;
+  } catch (...) {
+    return false;
+  }
+#else
+  return false;
+#endif
+}
+} // namespace margelo::nitro::nitrotracing

package/cpp/HermesSampling.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+namespace margelo::nitro::nitrotracing {
+/**
+ * Stops Hermes' process-wide sampling profiler through the Hermes C++ API.
+ * Returns false when this build does not link Hermes (the iOS build, where the
+ * profiler's own stop works) or when Hermes refuses the call.
+ */
+bool disableHermesSampling() noexcept;
+} // namespace margelo::nitro::nitrotracing