tools/profiler/docs/instrumenting-javascript.rst

   1 Instrumenting JavaScript
   2 ========================
   3
   4 There are multiple ways to use the profiler with JavaScript. There is the "JavaScript"
   5 profiler feature (via about:profiling), which enables stack walking for JavaScript code.
   6 This is most likely turned on already for every profiler preset.
   7
   8 In addition, markers can be created to specifically marker an instant in time, or a
   9 duration. This can be helpful to make sense of a particular piece of the front-end,
  10 or record events that normally wouldn't show up in samples.
  11
  12 .. note::
  13     This guide explains JavaScript markers in depth. To learn more about how to add a
  14     marker in C++ or Rust, please take a look at their documentation
  15     in :doc:`markers-guide` or :doc:`instrumenting-rust` respectively.
  16
  17 Markers in Browser Chrome
  18 *************************
  19
  20 If you have access to ChromeUtils, then adding a marker is relatively easily.
  21
  22 .. code-block:: javascript
  23
  24   // Add an instant marker, representing a single point in time
  25   ChromeUtils.addProfilerMarker("MarkerName");
  26
  27   // Add a duration marker, representing a span of time.
  28   const startTime = Cu.now();
  29   doWork();
  30   ChromeUtils.addProfilerMarker("MarkerName", startTime);
  31
  32   // Add a duration marker, representing a span of time, with some additional tex
  33   const startTime = Cu.now();
  34   doWork();
  35   ChromeUtils.addProfilerMarker("MarkerName", startTime, "Details about this event");
  36
  37   // Add an instant marker, with some additional tex
  38   const startTime = Cu.now();
  39   doWork();
  40   ChromeUtils.addProfilerMarker("MarkerName", undefined, "Details about this event");
  41
  42 Markers in Content Code
  43 ***********************
  44
  45 If instrumenting content code, then the `UserTiming`_ API is the best bet.
  46 :code:`performance.mark` will create an instant marker, and a :code:`performance.measure`
  47 will create a duration marker. These markers will show up under UserTiming in
  48 the profiler UI.
  49
  50 .. code-block:: javascript
  51
  52   // Create an instant marker.
  53   performance.mark("InstantMarkerName");
  54
  55   doWork();
  56
  57   // Measuring with the performance API will also create duration markers.
  58   performance.measure("DurationMarkerName", "InstantMarkerName");
  59
  60 .. _UserTiming: https://developer.mozilla.org/en-US/docs/Web/API/User_Timing_API