Find out why a tap "did nothing".
Try the live demo: tap a slow button in your browser and watch the trace, including the spans it sends to OpenTelemetry.
Often the button worked. The JS thread was busy, so nothing appeared for a few seconds, and the person tapped again. Sometimes the second tap even undid the first. This package records the few facts that tell those cases apart:
- the JS thread was blocked, and for how long
- the time from a tap to the first visible response, and how many repeat taps came while people waited
- why a component rendered again: which props changed, and which only became a new object with the same contents
It is plain TypeScript with no native code. It works the same in React Native (iOS and Android) and in React on the web, and its output can be read in release builds on a real device.
It can also send every record to OpenTelemetry, so taps and JS-thread blocks show up next to your other traces (see Sending traces to OpenTelemetry).
Not a medical device. This is a debugging tool for app developers. It measures how an app responds to taps and renders, never anything about a person's health, and it makes no clinical claim. It records only what the app passes to it: never put personal or health data in a trace.
npm install @molecare/rn-traceReact (18 or later) is needed only for the hooks in @molecare/rn-trace/react.
No other dependencies. Every version from 0.2.0 is published from GitHub Actions with npm provenance, so you can check it was built from this repository.
import {
consoleSink,
createInteraction,
createTracer,
watchJsThread,
} from '@molecare/rn-trace';
export const tracer = createTracer({
tag: 'app',
sink: consoleSink(),
enabled: true, // switch off for production, see below
});
// Anywhere in the app's start-up:
watchJsThread(tracer);
// For one control:
const takePhoto = createInteraction(tracer, 'take-photo');
function onPress() {
takePhoto.start();
openSheet();
}
function onSheetShown() {
takePhoto.respond('sheet');
}In a component:
import { useMountTrace, useRenderTrace } from '@molecare/rn-trace/react';
function MoleRow({ mole, onSelect }: Props) {
useRenderTrace(tracer, 'MoleRow', { mole, onSelect });
useMountTrace(tracer, 'MoleRow');
// ...
}[app] +8210ms tap {"name":"take-photo"}
[app] +9520ms repeat-tap (!) {"name":"take-photo","waitingMs":1310,"repeats":1}
[app] +10790ms js-thread-blocked 2580ms (!) {"blockedMs":2580}
[app] +10810ms responded 2600ms (!) {"name":"take-photo","label":"sheet","repeats":1,"slow":true}
[app] +10812ms render {"name":"MoleRow","count":2,"changed":["mole","onSelect"],"sameContent":["mole","onSelect"]}
Read top to bottom: the tap arrived, the person tapped again after 1.3 s, the JS thread had been blocked for 2.6 s, and the sheet appeared only then. The button was not dead. Something kept the thread busy. Then MoleRow rendered again only because its props were new objects with the same contents.
consoleSink() picks the console method for you. In a React Native release build it uses console.error, because on iOS console.log and console.info are dropped there and console.error still reaches the device log. Everywhere else it uses console.log. That includes React Native debug builds, where console.error would open a red LogBox for every line.
- iOS over USB:
idevicesyslog -p <AppName>(from libimobiledevice), or Console.app. Search for your tag. - iOS over Wi-Fi:
idevicesyslogcannot see a phone that is paired only over the network, andlog collectneedssudo. Console.app still works. To read the trace from a script without a cable, write it to a file too (below). - Android:
adb logcat -s ReactNativeJS. - Web: the browser console.
In a React Native release build on iOS, JS console output goes only to the unified log (os_log). It does not appear in the app's stdout, so xcrun devicectl device process launch --console does not show it.
A sink is a plain function, so it can also append each line to a file in the app's Documents folder. This uses react-native-fs; any file API works.
import RNFS from 'react-native-fs';
import {
combineSinks,
consoleSink,
createTracer,
formatRecord,
} from '@molecare/rn-trace';
const file = `${RNFS.DocumentDirectoryPath}/rn-trace.log`;
let writes = RNFS.writeFile(file, '', 'utf8').catch(() => {});
const fileSink = (record) => {
const line = `${formatRecord(record)}\n`;
// One write after another, so lines never interleave.
writes = writes
.then(() => RNFS.appendFile(file, line, 'utf8'))
.catch(() => {});
};
const tracer = createTracer({
tag: 'app',
sink: combineSinks(consoleSink(), fileSink),
});For a development-signed build, copy it to the Mac over Wi-Fi:
xcrun devicectl device copy from --device <UDID> \
--domain-type appDataContainer --domain-identifier <bundle id> \
--source Documents/rn-trace.log --destination ./rn-trace.logLeave the file sink out of App Store builds: the file stays on the device and holds whatever you trace.
To choose yourself: consoleSink({ method: 'log', warnMethod: 'warn' }).
To attach the last records to a bug report instead, keep them in memory:
import {
combineSinks,
consoleSink,
createMemorySink,
} from '@molecare/rn-trace';
const memory = createMemorySink(500);
const tracer = createTracer({ sink: combineSinks(consoleSink(), memory.sink) });
// later: memory.records()otelSink turns every record into an OpenTelemetry span, so taps, JS-thread blocks and slow responses show up next to your other traces (Jaeger, Grafana Tempo, Honeycomb, Datadog, anything that takes OTLP). rn-trace imports nothing from OpenTelemetry: pass the tracer your app already has.
import { trace } from '@opentelemetry/api';
import {
combineSinks,
consoleSink,
createTracer,
otelSink,
} from '@molecare/rn-trace';
const tracer = createTracer({
tag: 'app',
sink: combineSinks(
consoleSink(),
otelSink({ tracer: trace.getTracer('my-app') })
),
});- A measured record (
js-thread-blocked,responded, aspan,time(...)) becomes a span with its real start and end. An instant event (tap,render) becomes a span of no length. - The span is named after the event. Attributes are
rn_trace.tag,rn_trace.level,rn_trace.at_ms,rn_trace.duration_msand the record's data asrn_trace.data.<key>. Strings, numbers, booleans and arrays of one of those are kept; other values become JSON strings;null,undefined,NaNandInfinityare left out. - Options:
prefix(defaultrn_trace),spanName(record), andclockfor tests.
Setting up the OpenTelemetry SDK and an exporter is up to the app; the sink only needs trace.getTracer(...) to return a working tracer. What you trace goes wherever that exporter sends it, so the same rule applies: no personal or health data in data.
| Option | Default | Meaning |
|---|---|---|
tag |
'trace' |
Shown at the start of every line. |
sink |
none | Where records go. Without a sink nothing is written. |
enabled |
true |
A disabled tracer records nothing and costs very little. |
now |
performance.now() |
Milliseconds clock, for tests. |
The tracer has:
trace(event, data?)andwarn(event, data?)span(event), which returns{ end(data?) }.endrecords the duration once and returns it.time(event, fn), which runsfnand records how long it took. For a promise it waits until the promise settles. A failure is recorded with{ failed: true }and still thrown.measured(event, durationMs, data?, level?), for a duration measured elsewherenow(), which returns the milliseconds since the tracer was created
There is no global tracer. Create one and pass it where it is needed.
This checks every intervalMs (100). When a check arrives at least thresholdMs (250) late, it records js-thread-blocked as a warning with blockedMs. It returns a function that stops it.
start(data?): call it on the tap. A tap while one is still waiting is recorded asrepeat-tap.respond(label?, data?): call it when something visible happens. This recordsrespondedwith the time since the first tap and the number of repeats. Responses slower thanslowMs(300) are recorded as warnings.cancel()forgets a pending tap.pendingtells whether one is waiting.
This records every committed render with changed (the props that differ by reference). It also records sameContent: the changed props that are functions, or arrays or objects with the same contents as before. Those usually mean a parent creates them anew on each render, so a memoised child or an effect runs again for nothing. A render with propsSame: true changed no prop at all: the component's own state changed, a context it reads changed, or its parent rendered again and it is not memoised.
This records mount, and on unmount it records unmount with how long the component was shown.
consoleSink(options?)writes one line per record.createMemorySink(limit = 500)returns{ sink, records, clear }.combineSinks(...sinks)sends each record to every sink.formatRecord(record)returns the lineconsoleSinkwrites.
A sink that throws never breaks the app.
Pass enabled: false, for example enabled: __DEV__ || isInternalBuild. Every call then returns at once, and watchJsThread does not start a timer.
Do not put personal data in data. Anything you pass ends up in a device log.
The live demo is in demo/. It imports the package from src/, so it always shows the code on main. Run it locally with npm run demo.
Apache-2.0. Made by MoleCare.