JS Self-Profiling API

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT REQUIRED, RECOMMENDED, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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.

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.
   Note

   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.

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. Let marker be the result of running the capture a marker algorithm given the profiling session's associated environment settings object.
7. If marker is not null, set the ProfilerSample.marker property of sample to marker.
8. Add sample to the ProfilerTrace.samples associated with the session's ProfilerTrace.

To capture a marker given an environment settings object settings, perform the following steps:

1. Let candidateMarker be the ProfilerMarker value that best describes the top-level work the user agent was performing on the profiling session's agent when the sample was taken, or null if none applies.
2. If candidateMarker is null, return null.
3. If the work described by candidateMarker was performed for a specific document that is not same origin with the origin of settings, return null.
4. Return the result of running filter a marker given candidateMarker and settings.

To filter a marker given a ProfilerMarker marker and an environment settings object settings, perform the following steps:

1. If settings' cross-origin isolated capability is true, return marker.
2. If marker is "style" or "layout", return marker.
3. Return null.

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 instance be equal to the function instance associated with context.
3. Let scriptOrModule be equal to the ScriptOrModule associated with context.
4. Let attributedScriptOrModule be equal to the result of running the following algorithm:
   1. If scriptOrModule is non-null, return scriptOrModule.
   2. If instance is a built-in function object, return the ScriptOrModule containing the function that invoked instance.
      Editor's note

      The purpose of the above logic is to ensure that built-in functions invoked by inaccessible scripts are not exposed in traces, by using the ScriptOrModule that invoked them for attribution.

      Issue

      "[...] the ScriptOrModule containing the function that invoked instance" should be defined more rigorously. We could leverage the top-most execution context on the stack that defines a ScriptOrModule to provide this, but it's not ideal -- there may (theoretically) be other mechanisms for a builtin to be enqueued on the execution context stack, in which case the attribution would be invalid.

   3. Otherwise, return null.
5. If attributedScriptOrModule is null, return undefined.
6. Let attributedScript be the script obtained from attributedScriptOrModule.[[HostDefined]].
7. If attributedScript is a classic script and its muted errors boolean is equal to true, return undefined.
   Editor's note

   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.

8. Let frame be a new ProfilerFrame.
9. Set ProfilerFrame.name of frame to the function instance name associated with instance.
10. If scriptOrModule is non-null:
    1. Let script be the script obtained from scriptOrModule.[[HostDefined]].
    2. Let resourceString be equal to the base URL of script.
    3. Set ProfilerFrame.resourceId to the result of running get an element ID on resourceString and ProfilerTrace.resources.
    4. Set ProfilerFrame.line of frame to the 1-based index of the line at which instance is defined in script.
    5. Set ProfilerFrame.column of frame to the 1-based index of the column at which instance is defined in script.
11. 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.

WebIDL[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.

WebIDLtypedef 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.

WebIDLenum ProfilerMarker { "script", "gc", "style", "layout", "paint", "other" };

dictionary ProfilerSample {
  required DOMHighResTimeStamp timestamp;
  unsigned long long stackId;
  ProfilerMarker? marker;
};

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

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

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

ProfilerInitOptions MUST support the following fields:

• sampleInterval is the application's desired sample interval. This value MUST be greater than or equal to zero.
• maxBufferSize is the desired sample buffer size limit, in samples.

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

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