|
|
@@ -0,0 +1,185 @@ |
|
|
# Interaction tracking with React |
|
|
|
|
|
React recently introduced an [experimental profiler API](https://github.com/reactjs/rfcs/pull/51). After discussing this API with several teams at Facebook, one common piece of feedback was that the performance information would be _more useful_ if it could be associated with the events that caused the application to render (e.g. button click, XHR response). Tracking these events (or "interactions") would enable more powerful tooling to be built around the timing information, capable of answering questions like "_What caused this really slow commit?_" or "_How long does it typically take for this interaction to update the DOM?_". |
|
|
|
|
|
With version 16.4.3, React added experimental support for this tracking by way of a new NPM package, [schedule](https://www.npmjs.com/package/schedule). However the public API for this package is **not yet finalized** and will likely change with upcoming minor releases, so it should be **used with caution**. |
|
|
|
|
|
This Gist provides some high-level documentation for anyone looking to experiment with the API. |
|
|
|
|
|
#### WARNING: "unstable_" APIs may change in any version without respecting semver |
|
|
|
|
|
React has always respected semantic versioning for its public API. However, sometimes we want to share an early preview of something that is likely to change in the future. This is one of those cases. If you care about semantic versioning guarantees, don't use "unstable_" APIs because they are subject to change in any patch release. If you use them, you agree that things will break between releases, and that you use a lockfile to avoid that. |
|
|
|
|
|
## Overview |
|
|
|
|
|
An interaction is a descriptive string (e.g. "login button clicked") and a timestamp. When you declare an interaction, you also provide a callback in which to do some work related to that interaction. Interactions are similar to ["zones"](https://github.com/domenic/zones) in that any work done within the "zone" is attributed to the interaction. |
|
|
|
|
|
For example, you can track a React render like so: |
|
|
```js |
|
|
import { unstable_Profiler as Profiler } from "react"; |
|
|
import { render } from "react-dom"; |
|
|
import { unstable_track as track } from "schedule/tracking"; |
|
|
|
|
|
track("initial render", performance.now(), () => |
|
|
render( |
|
|
<Profiler id="Application" onRender={onRender}> |
|
|
<Application /> |
|
|
</Profiler> |
|
|
) |
|
|
); |
|
|
``` |
|
|
|
|
|
In the above example, the profiler's `onRender` prop will be called after the application renders and mounts. Among [other things](https://github.com/bvaughn/rfcs/blob/profiler/text/0000-profiler.md#detailed-design), it will receive a parameter that specifies the `Set` of interactions that were part of that render (i.e. the "_initial render_" interaction). |
|
|
|
|
|
The interaction will also appear in the [React DevTools profiler plug-in](https://github.com/facebook/react-devtools/pull/1069). |
|
|
|
|
|
## API |
|
|
|
|
|
The following methods are a subset of the interaction tracking API. |
|
|
|
|
|
### unstable_track |
|
|
```js |
|
|
unstable_track( |
|
|
name: string, |
|
|
timestamp: number, |
|
|
callback: () => T |
|
|
) => T |
|
|
``` |
|
|
Tracks a new interaction (by appending to the existing set of interactions). The callback function will be executed and its return value will be returned to the caller. Any code run within that callback will be attributed to that interaction. Calls to `unstable_wrap()` will schedule async work within the same zone. |
|
|
|
|
|
### unstable_wrap |
|
|
```js |
|
|
unstable_wrap(callback: Function) => Function |
|
|
``` |
|
|
Wrap a function for later execution within the current interaction "zone". When this function is later run, interactions that were active when it was "wrapped" will be reactivated. |
|
|
|
|
|
The wrapped function returned also defines a `cancel()` property which can be used to notify any tracked interactions that the async work has been cancelled. |
|
|
|
|
|
## Examples |
|
|
|
|
|
### Tracking initial render |
|
|
```js |
|
|
import { unstable_track as track } from "schedule/tracking"; |
|
|
|
|
|
track("initial render", performance.now(), () => render(<Application />)); |
|
|
``` |
|
|
|
|
|
### Tracking state updates |
|
|
```js |
|
|
import { unstable_track } from "schedule/tracking"; |
|
|
|
|
|
class MyComponent extends Component { |
|
|
handleLoginButtonClick = event => { |
|
|
unstable_track("Login button click", performance.now(), () => { |
|
|
this.setState({ isLoggingIn: true }); |
|
|
}); |
|
|
}; |
|
|
|
|
|
// render ... |
|
|
} |
|
|
``` |
|
|
|
|
|
### Tracking async work |
|
|
```js |
|
|
import { unstable_track, unstable_wrap } from "schedule/tracking"; |
|
|
|
|
|
unstable_track("Some event", performance.now(), () => { |
|
|
setTimeout( |
|
|
unstable_wrap(() => { |
|
|
// Do some async work |
|
|
}) |
|
|
); |
|
|
}); |
|
|
``` |
|
|
ly introduced an [experimental profiler API](https://github.com/reactjs/rfcs/pull/51). After discussing this API with several teams at Facebook, one common piece of feedback was that the performance information would be _more useful_ if it could be associated with the events that caused the application to render (e.g. button click, XHR response). Tracking these events (or "interactions") would enable more powerful tooling to be built around the timing information, capable of answering questions like "_What caused this really slow commit?_" or "_How long does it typically take for this interaction to update the DOM?_". |
|
|
|
|
|
With version 16.4.3, React added experimental support for this tracking by way of a new NPM package, [schedule](https://www.npmjs.com/package/schedule). However the public API for this package is **not yet finalized** and will likely change with upcoming minor releases, so it should be **used with caution**. |
|
|
|
|
|
This Gist provides some high-level documentation for anyone looking to experiment with the API. |
|
|
|
|
|
### A warning about "unstable_" APIs |
|
|
**APIs prefixed with "unstable_" can change in any version without respecting semver.** |
|
|
|
|
|
React has always respected semantic versioning for its public API. However, sometimes we want to share an early preview of something that is likely to change in the future. This is one of those cases. If you care about semantic versioning guarantees, don't use "unstable_" APIs because they are subject to change in any patch release. If you use them, you agree that things will break between releases, and that you use a lockfile to avoid that. |
|
|
|
|
|
## Overview |
|
|
|
|
|
An interaction is a descriptive string (e.g. "login button clicked") and a timestamp. When you declare an interaction, you also provide a callback in which to do some work related to that interaction. Interactions are similar to ["zones"](https://github.com/domenic/zones) in that any work done within the "zone" is attributed to the interaction. |
|
|
|
|
|
For example, you can track a React render like so: |
|
|
```js |
|
|
import { unstable_Profiler as Profiler } from "react"; |
|
|
import { render } from "react-dom"; |
|
|
import { unstable_track as track } from "schedule/tracking"; |
|
|
|
|
|
track("initial render", performance.now(), () => |
|
|
render( |
|
|
<Profiler id="Application" onRender={onRender}> |
|
|
<Application /> |
|
|
</Profiler> |
|
|
) |
|
|
); |
|
|
``` |
|
|
|
|
|
In the above example, the profiler's `onRender` prop will be called after the application renders and mounts. Among [other things](https://github.com/bvaughn/rfcs/blob/profiler/text/0000-profiler.md#detailed-design), it will receive a parameter that specifies the `Set` of interactions that were part of that render (i.e. the "_initial render_" interaction). |
|
|
|
|
|
The interaction will also appear in the [React DevTools profiler plug-in](https://github.com/facebook/react-devtools/pull/1069). |
|
|
|
|
|
## API |
|
|
|
|
|
The following methods are a subset of the interaction tracking API. |
|
|
|
|
|
### unstable_track |
|
|
```js |
|
|
unstable_track( |
|
|
name: string, |
|
|
timestamp: number, |
|
|
callback: () => T |
|
|
) => T |
|
|
``` |
|
|
Tracks a new interaction (by appending to the existing set of interactions). The callback function will be executed and its return value will be returned to the caller. Any code run within that callback will be attributed to that interaction. Calls to `unstable_wrap()` will schedule async work within the same zone. |
|
|
|
|
|
### unstable_wrap |
|
|
```js |
|
|
unstable_wrap(callback: Function) => Function |
|
|
``` |
|
|
Wrap a function for later execution within the current interaction "zone". When this function is later run, interactions that were active when it was "wrapped" will be reactivated. |
|
|
|
|
|
The wrapped function returned also defines a `cancel()` property which can be used to notify any tracked interactions that the async work has been cancelled. |
|
|
|
|
|
## Examples |
|
|
|
|
|
### Tracking initial render |
|
|
```js |
|
|
import { unstable_track as track } from "schedule/tracking"; |
|
|
|
|
|
track("initial render", performance.now(), () => render(<Application />)); |
|
|
``` |
|
|
|
|
|
### Tracking state updates |
|
|
```js |
|
|
import { unstable_track } from "schedule/tracking"; |
|
|
|
|
|
class MyComponent extends Component { |
|
|
handleLoginButtonClick = event => { |
|
|
unstable_track("Login button click", performance.now(), () => { |
|
|
this.setState({ isLoggingIn: true }); |
|
|
}); |
|
|
}; |
|
|
|
|
|
// render ... |
|
|
} |
|
|
``` |
|
|
|
|
|
### Tracking async work |
|
|
```js |
|
|
import { unstable_track, unstable_wrap } from "schedule/tracking"; |
|
|
|
|
|
unstable_track("Some event", performance.now(), () => { |
|
|
setTimeout( |
|
|
unstable_wrap(() => { |
|
|
// Do some async work |
|
|
}) |
|
|
); |
|
|
}); |
|
|
``` |
bvaughn revised this gist