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

Definitions

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 global object as defined in [[HTML]].
2. A state, which is one of {started, paused, stopped}.
3. 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.

4. An origin.
5. A time origin that samples' timestamps are measured relative to.
6. A sample buffer storing captured samples, with a finite sample buffer size limit.

Multiple profiling sessions on the same page SHOULD be supported.

Sampling Algorithm

This section is non-normative for now, the specifics currently being driven by results from a prototype implementation.

We define the sampling algorithm as follows:

1. Let env be the script execution environment of the profiling session.
2. Let stack be the stack of execution contexts associated with env.
3. For each execution context ec on stack:
   1. Let ecs be the script associated with ec.
   2. If the realm associated with ecs is not equal to the realm of the global object associated with the profiling session, skip.
   3. If the origin of the script associated with ecs is not equal to the origin of the browsing context, and its associated script tag (if present) does not pass a CORS check, skip.
   4. Otherwise, include the stack frame.
4. Record a new sample with all stack frames recorded in the algorithm, associated with the current timestamp relative to the browsing context's time origin.

The Profiler Interface

      [Exposed=(Window,Worker)]
      interface Profiler {
        readonly attribute DOMHighResTimeStamp sampleInterval;
        readonly attribute boolean stopped;

        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.

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 contain exactly all unique URIs captured during the profiling session.

The frames attribute MUST contain all frames recorded during the profiling session.

The stacks attribute MUST contain all stacks recorded during the profiling session.

The samples attribute MUST return all samples recorded during the profiling session, ordered from earliest to latest recorded.

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

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

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

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

Extensions to the Performance Interface

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

      [Exposed=(Window,Worker)]
      partial interface Performance {
        Promise<Profiler> profile(ProfilerInitOptions options);
      };
      

ProfilerInitOptions MUST support the following fields:

• ProfilerInitOptions.sampleInterval is the application's desired sample interval. This value MUST be greater than or equal to zero.
• ProfilerInitOptions.maxBufferSize is the desired maximum capacity of the created profiler's sample buffer, in samples.

Feature Policy

This specification defines a new policy-controlled feature that controls whether the Performance.profile method may be invoked.

The feature identifier for this feature is "js-profiling".

The default allowlist for this feature is "none".

Feature policy is leveraged here to give embedders the ability to control whether or not embedded frames may start profilers, as well as hint to the UA that the page may wish to initialize profiling. The default policy is false to allow JS engines to avoid storing any profiling metadata for documents that do not intend to profile themselves.