Skip to main content

Profiler

The profiler plugin allows recording JavaScript profiles in production.

Usage​

index.js
import { init, profiler } from "@palette.dev/browser";

init({
  // ...
  plugins: [profiler()],
});

profiler.on(
  ["paint.click", "paint.keydown", "paint.scroll", "paint.mousemove", "markers.measure", "events.load", "events.dcl"],
  {
    sampleInterval: 1,
    maxBufferSize: 100_000,
  }
);

Starting the Profiler​

To start the profiler, use the .on API to start profiling on specific events:

// Start the profiler on the "Click to Paint" event
profiler.on(["paint.click"], {
  sampleInterval: 1,
  maxBufferSize: 100_000,
});

All future calls to .on are ignored, until .off is called.

The sampling interval allows you to specify how often you want profile samples to be taken. The max buffer size is the maximum number of samples to collect before stopping the profiler. It ensures the profiler doesn't run forever.

Here are all the supported events:

  • "paint.click" - Click to Paint
  • "paint.keydown" - Keydown to Paint
  • "paint.scroll" - Scroll to Paint
  • "paint.mousemove" - Mousemove to Paint
  • "markers.mark" - Mark Event
  • "markers.measure" - Measure Event
  • "events.load" - Load Event
  • "events.dcl" - DOM Content Loaded

Stopping the Profiler​

To stop starting the profiler on events, use the profiler.off API:

profiler.off();

The .off API isn't required to stop the profiler. The profiler will stop automatically after 1s of user inactivity.

Use the .off API if you only want to profile a specific part of your application. In React, you can use the useEffect hook to start and stop the profiler.

Here is an example of starting the profiler on paint.click events and stopping it when the component unmounts:

index.jsx
const MyComponent = () => {
  useEffect(() => {
    profiler.on(["paint.click"], opts);
    return () => profiler.off();
  }, []);

  return <>...</>;
};

Picking a Sampling Interval​

What is a Sampling Interval?​

Palette's profiler is a sampling profiler, meaning it takes a snapshot of the current function stack in intervals. As an example, if your sampling interval is 1ms, then the profiler will collect 1 sample every 1ms.

Tradeoffs and Recommendations​

A sampling interval and max buffer size are required to start the profiler. These values determine the overhead the profiler has on your app.

Small sampling intervals give you greater precision of observability into function execution at the cost of overhead, and larger sampling intervals mean less overhead but less precision.

Recommendations for profiling interactions​

  • 1ms sampling interval - Ideal for short and frequent events like user interactions and animations.

For profiling interactivity, we recommend setting a sampling interval that is less than 16ms. Because browsers usually paint every 16ms, setting a sampling interval greater than 16ms will miss collecting function calls during execution.

Recommendations for profiling page load​

  • 10ms sampling interval - Ideal for long and infrequent events like page load.

Collected Events​

All events are compressed asynchronously off the main thread to minimize network overhead. See the overhead docs for more details.

© 2024 Redraw, Inc.