# Profiler

React 16.4 will introduce a new `Profiler` component (initially exported as `React.unstable_Profiler`) for collecting render timing information in order to measure the "cost" of rendering for both sync and async modes.

`Profiler` timing metrics are significantly faster than those built around the User Timing API, and as such we plan to provide a production+profiling bundle in the future. (The initial release will only log timing information in DEV mode, although the component will still render its children- without timings- in production mode.)

## How is it used?

`Profiler` can be declared anywhere within a React tree to measure the cost of rendering that portion of the tree. For example, a `Navigation` component and its descendants:
```js
const Profiler = React.unstable_Profiler;

render(
  <App>
    <Profiler id="Navigation" onRender={callback}>
      <Navigation {...props} />
    </Profiler>
    <Main {...props} />
  </App>
);
```

Multiple `Profiler`s can be used to measure different parts of an application:
```js
const Profiler = React.unstable_Profiler;

render(
  <App>
    <Profiler id="Navigation" onRender={callback}>
      <Navigation {...props} />
    </Profiler>
    <Profiler id="Main" onRender={callback}>
      <Main {...props} />
    </Profiler>
  </App>
);
```

`Profiler`s can also be nested to measure different components within the same subtree:
```js
const Profiler = React.unstable_Profiler;

render(
  <App>
    <Profiler id="Panel" onRender={callback}>
      <Panel {...props}>
        <Profiler id="Content" onRender={callback}>
          <Content {...props} />
        </Profiler>
        <Profiler id="PreviewPane" onRender={callback}>
          <PreviewPane {...props} />
        </Profiler>
      </Panel>
    </Profiler>
  </App>
);
```

Although `Profiler` is a light-weight component, it should be used sparingly. Every component adds CPU and memory overhead to an application.

## `onRender` callback

The `onRender` callback is called each time the root renders. It receives the following parameters:
* `id: string` - The `id` value of the `Profiler` tag that was measured. (This `id` can change between renders if it is derived from `state` or `props`.)
* `phase: string` - Either "mount" or "update" (depending on whether this root was newly mounted or has just been updated).
* `actualTime: number` - Time spent rendering the `Profiler` and its descendants for the most recent "mount" or "update" render. <sup>1</sup>
* `baseTime: number` - Duration of the most recent `render` time for each individual component within the `Profiler` tree. <sup>1</sup>
* `startTime: number` - When the `Profiler` began the recently committed render. <sup>2</sup>
* `commitTime: number` - The time at which the current commit took place. <sup>2</sup>

<sup>1: See [**"Timing metrics"**](#timing-metrics) section below for more detailed information about what this time represents.</sup>

<sup>2: See [**"Start and commit times"**](#start-and-commit-times) section below for more detailed information about what this time represents.</sup>

## Timing metrics

Here is a review of the types of timing React is now capable of reporting:

#### User Timing API

Measures start/stop times for each component lifecycle.

* **Opt in mechanism**: Feature flag (typically DEV mode only)
* **Scope**: Tracked for all components in an app
* **How is it measured?**
    * Start/stop times for each component lifecycle
    * Measured as a realtime graph
* **When is it recorded?**
    * Realtime graph is recorded after each lifecycle call.
* **What does it tell us?**
    *  Flame graph paints a useful picture of how events (e.g. mouse clicks) tie together with rendering.

#### “Actual” render time (new)

Time spent rendering the `Profiler` and its descendants for the most recent render/update.

* **Opt in mechanism**: Wrap a component with `<Profiler>`
* **Scope**: Measured for descendants of `Profiler` only
* **How is it measured?**
    * Start timer during “begin” phase, stop during “complete” phase
    * Paused (and accumulated) for scheduling/timing interruptions <sup>3</sup>
    * Paused (and accumulated) for aborted renders (e.g. suspense)
* **When is it recorded?**
    * A new snapshot is recorded each time a `Profiler` is re-rendered
* **What does it tell us?**
    * How well does the subtree make use of `shouldComponentUpdate` for memoization?
    * The more this time decreases for update renders, the better the memoization.

#### “Base” render time (new)

Duration of the most recent `render` time for each individual component within the `Profiler` tree.

* **Opt in mechanism**: Wrap a component with `<Profiler>`
* **Scope**: Measured for descendants of `Profiler` only
* **How is it measured?**
    * Measured for each fiber below a `Profiler` component.
    * Recorded during “begin” phase.
        * Times are not updated/recorded if a component skips render because of `shouldComponentUpdate`
        * (Descendant times are also not updated in that case)
    * Bubble up (summed) for the `Profiler` during “complete” phase
    * Total times logged for `Profiler` (not for individual fibers)
* **When is it recorded?**
    * A new snapshot is recorded each time a `Profiler` is re-rendered
* **What does it tell us?**
    * How expensive our render functions are in the worst case (no memoization).
    * Lower this number by reducing the work done in render.

<sup>3: Until "resume" behavior is implemented, interruptions will not accumulate time.</sup>

## Start and commit times

At first glance, these values may seem redundant. Why is commit time necessary? Why isn't it just the time at which the `onRender` callback is called? And why is start time not just the commit time less the "actual" time?

#### Start time

Start time identifies when a particular commit started rendering. Although insufficient to determine the cause of the render, it can at least be used to rule out certain interactions (e.g. mouse click, Flux action). This may be helpful if you are also collecting other types of interactions and trying to correlate them with renders.

Start time isn't just the commit time less the "actual" time, because in async rendering mode React may yield during a render. This "yielded time" (when React was not doing work) is not included in either the "actual" or "base" time measurements.

#### Commit time

Commit time could be roughly determined using e.g. `performance.now()` within the `onRender` callback, but multiple `Profiler` components would end up with slightly different times for a single commit. Instead, an explicit time is provided (shared between all `Profiler`s in the commit) enabling them to be grouped if desirable.