Skip to main content

Profiling

Argent records a profile of the running app. The agent reads the profile. The agent tells you which component renders too often, which function uses the CPU, and where the app hangs or leaks memory.

The agent profiles a comments screen and finds a component that renders on every tick

Profilers​

Argent has two profilers. The agent can run one profiler or both profilers at the same time.

ProfilerPlatformsEngineData
ReactiOS simulators, Android, react-native-macosHermes and React DevToolsJS CPU samples, React commits, renders of each component
NativeiOS simulators, Mac appsXcode InstrumentsNative CPU time, UI hangs, memory leaks
NativeAndroidPerfettoNative CPU time, UI hangs with the jank reason, GC, memory growth

The React profiler connects to the Hermes runtime of the app through the debugger. Thus the app must run in a debuggable build. The native profiler attaches to the process of the app on the device. On iOS, the native profiler does not need a special build. See Profile your Mac app for Mac build requirements. On Android, the app must be a debug build or be profileable. Without this, the native profile has no CPU call stacks. To make a release build profileable, add <profileable android:shell="true"/> under <application> in AndroidManifest.xml.

A profiling session​

A profiling session has four steps. The agent does each step with one tool.

  1. The agent starts the profiler. From this moment, Argent records the data.
  2. You or the agent use the app. The agent can tap, swipe and type in the app with the interaction tools. This is the only part of the session that the profile contains.
  3. The agent stops the profiler. Argent collects the data and writes it to disk.
  4. The agent analyzes the data. Argent returns a report in Markdown.

A screen capture uses CPU on the device. On a phone, it also raises the clock speeds and makes the app look faster than it is. Thus Argent keeps the screen capture low while a profiler records:

  • Argent does not add the screenshot and the element tree after each interaction. The agent can still take a screenshot or read the element tree when it must see the screen. Each interaction still waits until the screen stops changing, so they show the screen after the interaction.
  • On an Android emulator or device, Argent tells the simulator-server to capture the screen only for a screenshot. This needs a simulator-server version with on-demand screenshots.
    • On an emulator, a screenshot takes one frame in about 100 ms. The capture does not start.
    • On a physical device, a screenshot takes about 150 ms to 200 ms. It starts the capture for a short time.
    • Taps and swipes do not start the capture.

Argent keeps returning screenshots and element trees if it cannot match a React recording to the device you are using. This can happen when several devices share Metro.

When no profiler records, a screenshot does not wait for the screen capture.

When the agent runs both profilers, the agent can also ask for a combined report. Argent aligns the native hangs with the React commits on the wall clock. Thus the report tells you which React commit caused which hang.

The report​

The React report lists the hot commits. A commit is hot when it takes 16 ms or more. For each hot commit, the report shows which components rendered, which component triggered the cascade, and which props changed. The report ends with a table of the components that rendered most.

The report also shows the share of the session that React spent rendering, and the largest share in one second. Idle time decreases the share of the session, but not the one-second value. When no commit is hot, the report lists the app components that use the most re-render time. A report with hot commits contains this list only when the list names a component that the table does not contain. A component that re-renders often but uses little time is not in the list. If Argent cannot read the source of the project, the list can also contain library components. The report does not say that the session is good or bad.

The native report lists the CPU hotspots, the hangs and the memory leaks. Each entry has a severity indicator and a suggestion.

Instruments reports list CPU time spent by Argent and Instruments separately from app hotspots. Hang reports label functions from either tool so you can recognize profiler and automation overhead.

The React report gives the file and the line of the components in its table that are in the project. When several files define the same name, the report also names the other files. For the five components with the highest render time, the report also shows a suggestion and, if it has the file, 50 lines of source. Thus the agent can propose a fix for the component.

Further investigation​

After the report, the agent can query the stored data without a new recording.

QueryContent
CommitsThe commits of one component or of a time window, the cascade tree of a commit, or render counts
CPUThe top functions, the CPU in a time window, the call tree of a function, or the CPU of a component
Native stacksThe stacks during a hang, the callers of a function, the CPU of each thread, or the leaked objects

Argent writes each session to disk in a directory with the name argent-profiler-cwd in the temporary directory of the system. The agent can load a session from disk later and query it again. Thus you can compare the profile before and after a change.

Example instructions​

  • "This screen scrolls slowly. Profile the scroll and tell me which component causes it."
  • "Start both profilers, open the details screen, and show me the hangs."
  • "Find the components that render more than 50 times during the session."
  • "Apply the fix, profile the same interaction again, and compare the results."

Limits​

  • Profiling is unavailable for Chromium and Electron apps.
  • Argent records the data from the start of the session only. Start the session before you do the interaction.
  • One session at a time can own the React profiler of an app. If another agent owns the session, Argent tells the agent who the owner is. The agent must ask you before it takes over the session.
  • A session is stale after 5 minutes without a heartbeat. Only react-profiler-status, react-profiler-renders and react-profiler-fiber-tree calls refresh the heartbeat, so a long recording can go stale while you use the app. An agent on another tool-server can take over a stale session without asking you. Argent tells both agents about the takeover. On React Native 0.84 and older, Metro allows one debugger for each app. A call from a second tool-server disconnects the first tool-server. Argent reports this loss to the first agent as a lost debugger connection, not as a takeover.
  • Agents on one tool-server share its sessions, because Argent cannot tell these agents apart. An agent can find a session that another agent started. If this session is stale, Argent tells the agent to ask you before it discards the session.
  • A JavaScript reload ends a React recording. After a lost debugger connection, Argent cannot collect the recording, even if the app continues to record. In both cases, Argent does not keep the data. The agent can ask Argent if the last recording was saved or lost.
  • A component that unmounts before the session stops can lose its name in the report. The report shows the duration of this work under "unattributed".
  • On iOS simulators and Mac apps, a leak can appear in an Instruments trace once a check that started after the leak finishes. Keep recording for about 25 seconds after the suspected leak. On Android, memory growth is a weak signal of a leak.
  • On Android, native network capture can slow the app and change the timings in a profile. When native network capture is on for an app on the device, the start of a profiler gives a warning. To profile without it, ask the agent to stop native network capture for the app. Then restart the app. See Network inspection.

Argent does this with the react-profiler-*, native-profiler-* and profiler-* tools. The tools reference contains all tools.