This specification describes an API that allows web applications to control a sampling profiler for measuring client JavaScript execution times.

Introduction

Complex web applications currently have limited visibility into where JS execution time is spent on clients. Without the ability to efficiently collect stack samples, applications are forced to instrument their code with profiling hooks that are imprecise and can significantly slow down execution. By providing an API to manipulate a sampling profiler, applications can gather rich execution data for aggregation and analysis with minimal overhead.

Examples

The following example demonstrates how a user may profile an expensive operation, gathering JS execution samples every 10ms. The trace can be sent to a server for analysis to debug outliers and JS execution characteristics in aggregate.

        const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 });
        const start = performance.now();
        for (let i = 0; i < 1000000; i++) {
             doWork();
        }
        const duration = performance.now() - start;
        const trace = await profiler.stop();
        const traceJson = JSON.stringify({
          duration,
          trace,
        });
        sendTrace(traceJson);
        

Another common real-world scenario is profiling JS across a pageload. This example profiles the onload event, sending performance timing data along with the trace.

        const profiler = new Profiler({ sampleInterval: 10, maxBufferSize: 10000 });

        window.addEventListener('load', async () => {
          const trace = await profiler.stop();
          const traceJson = JSON.stringify({
            timing: performance.timing,
            trace,
          });
          sendTrace(traceJson);
        });

        // Rest of the page's JS initialization logic
        

Definitions

A sample is a descriptor of the instantaneous state of execution at a given point in time. Each sample is associated with a stack.

A stack is a list of frames that MUST be ordered sequentially from outermost to innermost frame.

A frame is an element in the context of a stack containing information about the current execution state.

Profiling Sessions

A profiling session is an abstract producer of samples. Each session has:

  1. A state, which is one of {started, paused, stopped}.
  2. A sample interval, defined as the periodicity at which the session obtains samples.

    The UA is NOT REQUIRED to take samples at this rate. However, it is RECOMMENDED that sampling is prioritized to take samples at this rate to produce higher quality traces.

  3. An agent to profile.
  4. A realm to profile.
  5. A time origin that samples' timestamps are measured relative to.
  6. A sample buffer size limit.
  7. A ProfilerTrace storing captured samples.

Multiple profiling sessions on the same page SHOULD be supported.

States

In the started state, the UA SHOULD make a best-effort to capture samples by executing the take a sample algorithm [= in parallel =] each time the sample interval has elapsed. In the paused and stopped states, the UA SHOULD NOT capture samples.

Profiling sessions MUST begin in the started state.

The UA MAY move a session from started to paused, and from paused to started.

The user agent is RECOMMENDED to pause the sampling of a profiling session if the browsing context is not in the foreground.

A stopped session MUST NOT move to the started or paused states.

Processing Model

To take a sample given a profiling session, perform the following steps:

  1. If the length of ProfilerTrace.samples is greater than or equal to the sample buffer size limit associated with the profiling session, fire a new event of type samplebufferfull to the associated Profiler, move the state to stopped, and return.
  2. Let sample be a new ProfilerSample.
  3. Set the ProfilerSample.timestamp property of sample to the current high resolution time relative to the profiling session's time origin.
  4. Let stack be the execution context stack associated with the profiling session's agent.
  5. Set the ProfilerSample.stackId property of sample to the result of the get a stack ID algorithm on stack.
  6. Add sample to the ProfilerTrace.samples associated with the session's ProfilerTrace.

To get a stack ID given an execution context stack bound to stack, perform the following steps:

  1. If stack is empty, return undefined.
  2. Let head be the top element of stack, and tail be the remainder of stack after removing its top element.
  3. Let parentId be the result of calling get a stack ID recursively on tail.
  4. Let frameId be the result of calling get a frame ID on head.
  5. If frameId is undefined, return parentId.
  6. Let profilerStack be a new ProfilerStack with ProfilerStack.frameId equal to frameId, and ProfilerStack.parentId equal to parentId.
  7. Return the result of running get an element ID on profilerStack and ProfilerTrace.stacks.

To get a frame ID given an execution context bound to context, perform the following steps:

  1. If the [= realm =] associated with context does not match the realm associated with the profiling session, return undefined.
  2. Let frame be a new ProfilerFrame.
  3. Let instance be equal to the function instance associated with context.
  4. Set ProfilerFrame.name of frame to the function instance name associated with |instance|.
  5. Let scriptOrModule be equal to the ScriptOrModule associated with context.
  6. If |scriptOrModule| is non-null:

    Builtin functions have a null ScriptOrModule.

    1. Let script be the script obtained from scriptOrModule.[[\HostDefined]].
    2. If script is a classic script and its muted errors boolean is equal to true, return null.

      This check ensures that we avoid including stack frames from cross-origin scripts served in a CORS-cross-origin response. We may want to consider renaming muted errors to better reflect this use case.

    3. Let resourceString be equal to the base URL of script.
    4. Set ProfilerFrame.resourceId to the result of running get an element ID on resourceString and ProfilerTrace.resources.
    5. Set ProfilerFrame.line of frame to the 1-based index of the line at which instance is defined in its containing script.
    6. Set ProfilerFrame.column of frame to the 1-based index of the column at which instance is defined in its containing script.
  7. Return the result of running get an element ID on frame and ProfilerTrace.frames.

To get an element ID for an item in a list, run the following steps:

  1. If there exists an element in list component-wise equal to item, return its index.
  2. Otherwise, append item to the end of list and return its index.

The Profiler Interface

      [Exposed=Window]
      interface Profiler : EventTarget {
        readonly attribute DOMHighResTimeStamp sampleInterval;
        readonly attribute boolean stopped;

        constructor(ProfilerInitOptions options);
        Promise<ProfilerTrace> stop();
      };
      

Each Profiler MUST be associated with exactly one profiling session.

The sampleInterval attribute MUST reflect the sample interval of the associated profiling session expressed as a DOMHighResTimeStamp.

The stopped attribute MUST be true if and only if the profiling session has state stopped.

{{Profiler}} is only exposed on {{Window}} until consensus is reached on [[Permissions-Policy]] and {{Worker}} integration.

new Profiler(options)

new Profiler(options) runs the following steps given an object options of type ProfilerInitOptions:
  1. If options' {{ProfilerInitOptions/sampleInterval}} is less than 0, throw a RangeError.
  2. Get the policy value for "js-profiling" in the Document. If the result is false, throw a "NotAllowedError" DOMException.
  3. Create a new profiling session where:
    1. The associated sample interval is set to either ProfilerInitOptions.sampleInterval OR the next lowest interval supported by the UA.
    2. The associated time origin is equal to the time origin of the current global object.
    3. The associated sample buffer size limit is set to {{ProfilerInitOptions/maxBufferSize}}.
    4. The associated [= agent =] is set to the surrounding agent.
    5. The associated [= realm =] is set to the current realm record.
    6. The associated ProfilerTrace is set to «[{{ProfilerTrace/resources}} → «», {{ProfilerTrace/frames}} → «», {{ProfilerTrace/stacks}} → «», {{ProfilerTrace/samples}} → «»]».
  4. Return a new Profiler associated with the newly created profiling session.

stop() method

Stops the profiler and returns a trace. This method MUST run these steps:

  1. If the associated [= profiling session =]'s state is stopped, return [= a promise rejected with =] an "InvalidStateError" DOMException.
  2. Set the [= profiling session =]'s state to stopped.
  3. Let |p:Promise| be [= a new promise =].
  4. Run the following steps [= in parallel =]:
    1. Perform any [= implementation-defined =] work to stop the [= profiling session =].
    2. Resolve |p| with the {{ProfilerTrace}} associated with the profiler's [= profiling session =].
  5. Return |p|.

Any samples taken after stop() is invoked SHOULD NOT be included by the profiling session.

The ProfilerTrace Dictionary

      typedef DOMString ProfilerResource;

      dictionary ProfilerTrace {
        required sequence<ProfilerResource> resources;
        required sequence<ProfilerFrame> frames;
        required sequence<ProfilerStack> stacks;
        required sequence<ProfilerSample> samples;
      };
      

The resources attribute MUST return the ProfilerResource list set by the take a sample algorithm.

The frames attribute MUST return the ProfilerFrame list set by the take a sample algorithm.

The stacks attribute MUST return the ProfilerStack list set by the take a sample algorithm.

The samples attribute MUST return the ProfilerSample list set by the take a sample algorithm.

Inspired by the V8 trace event format and Gecko profile format, this representation is designed to be easily and efficiently serializable.

The ProfilerSample Dictionary

        dictionary ProfilerSample {
          required DOMHighResTimeStamp timestamp;
          unsigned long long stackId;
        };
        

timestamp MUST return the value it was initialized to.

stackId MUST return the value it was initialized to.

The ProfilerStack Dictionary

        dictionary ProfilerStack {
          unsigned long long parentId;
          required unsigned long long frameId;
        };
        

parentId MUST return the value it was initialized to.

frameId MUST return the value it was iniitalized to.

The ProfilerFrame Dictionary

        dictionary ProfilerFrame {
          required DOMString name;
          unsigned long long resourceId;
          unsigned long long line;
          unsigned long long column;
        };
        

name MUST return the value it was initialized to.

resourceId MUST return the value it was initialized to.

line MUST return the value it was initialized to.

column MUST return the value it was initialized to.

The ProfilerInitOptions dictionary

      dictionary ProfilerInitOptions {
        required DOMHighResTimeStamp sampleInterval;
        required unsigned long maxBufferSize;
      };
      

ProfilerInitOptions MUST support the following fields:

Document Policy

This spec defines a configuration point in Document Policy with name js-profiling. Its type is boolean with default value false.

Document policy is leveraged to give UAs the ability to avoid storing required metadata for profiling when the document does not explicitly request it. While this metadata could conceivably be generated in response to a profiler being started, we store this bit on the document in order to signal to the engine as early as possible (as profiling early in page load is a common use case). This overhead may be non-trivial depending on the implementation, and therefore we default to false.

Automation

For the purposes of user-agent automation and application testing, this document defines the following [[WebDriver]] extension command.

Force Sample

HTTP Method URI Template
POST `/session/{session id}/forcesample`

The Force Sample extension command forces all [=profiling sessions=] to [=take a sample=] for the purpose of enabling more deterministic testing.

The remote end steps are:

  1. Let |sessions:list| be a [=list=] of all [=profiling sessions=] created in the current browsing context.
  2. For each |session:profiling session| of |sessions|:
    1. If the [=state=] of |session| is started, [=take a sample=] with |session|.
  3. Return success with data null.

Privacy and Security

The following sections detail some of the privacy and security choices of the API, illustrating protection strategies against various types of attacks.

Cross-origin script contents

The API avoids exposing contents of cross-origin scripts by requiring all functions included via the take a sample algorithm to be defined in a script served with CORS-same-origin through the muted errors property. Browser builtins (such as performance.now()) may still be included when invoked from cross-origin no-cors script (albeit with no information about the invoking script, line, or column number), although this is already made possible through manually overriding global objects.

As a result, the API does not expose any new insight into the contents or execution characteristics of cross-origin script, beyond what is already possible through manual instrumentation. UAs are encouraged to verify this holds if they choose to support extremely low sample interval values (e.g. less than one millisecond).

Cross-origin execution

Cross-origin execution contexts should not be observable by the API through the realm check in the take a sample algorithm. Cross-origin iframes and other execution contexts that share an agent with a profiler will therefore not have their execution observable through this API.

Timing attacks

Timing attacks remain a concern for any API that could introduce a new source of high-resolution timing information. Timestamps gathered in traces should be obtained from the same source as [[?HR-Time]]'s current high resolution time to avoid exposing a new vector for side-channel attacks.

See [[?HR-Time]]'s discussion on clock resolution.