이 명세는 클라이언트 JavaScript 실행 시간을 측정하기 위한 샘플링 프로파일러를 웹 애플리케이션이 제어할 수 있도록 하는 API를 설명한다.

정의

샘플은 주어진 시점에서의 순간적인 실행 상태를 설명하는 기술자이다. 각 샘플은 스택과 연결된다.

스택은 가장 바깥쪽 프레임부터 가장 안쪽 프레임까지 순차적으로 정렬되어야 하는 프레임 목록이다.

프레임은 현재 실행 상태에 관한 정보를 포함하는 스택 컨텍스트의 요소이다.

프로파일링 세션

프로파일링 세션은 샘플을 생성하는 추상적인 생성자이다. 각 세션에는 다음이 있다.

1. {started, paused, stopped} 중 하나인 상태.
2. 세션이 샘플을 획득하는 주기성으로 정의되는 샘플 간격.

   UA는 반드시 이 빈도로 샘플을 수집할 필요는 없다. 그러나 더 높은 품질의 추적 데이터를 생성하기 위해 이 빈도로 샘플을 수집하도록 샘플링에 우선순위를 부여하는 것이 좋다.

3. 프로파일링할 에이전트.
4. 프로파일링할 렐름.
5. 샘플의 타임스탬프가 이를 기준으로 측정되는 시간 원점.
6. 샘플 버퍼 크기 제한.
7. 캡처한 샘플을 저장하는 ProfilerTrace.

동일한 페이지에서 여러 프로파일링 세션을 지원하는 것이 좋다.

처리 모델

프로파일링 세션이 주어졌을 때 샘플을 수집하려면 다음 단계를 수행한다.

1. ProfilerTrace.samples의 길이가 프로파일링 세션과 연결된 샘플 버퍼 크기 제한보다 크거나 같으면, 연결된 Profiler에 samplebufferfull 유형의 새 이벤트를 발생시키고 상태를 stopped로 전환한 후 반환한다.
2. sample을 새 ProfilerSample로 설정한다.
3. sample의 ProfilerSample.timestamp 속성을 프로파일링 세션의 시간 원점을 기준으로 한 현재 고해상도 시간으로 설정한다.
4. stack을 프로파일링 세션의 에이전트와 연결된 실행 컨텍스트 스택으로 설정한다.
5. sample의 ProfilerSample.stackId 속성을 stack에 스택 ID 가져오기 알고리즘을 실행한 결과로 설정한다.
6. sample을 세션의 ProfilerTrace와 연결된 ProfilerTrace.samples에 추가한다.

stack에 바인딩된 실행 컨텍스트 스택이 주어졌을 때 스택 ID를 가져오려면 다음 단계를 수행한다.

1. stack이 비어 있으면 undefined를 반환한다.
2. head를 stack의 최상위 요소로 설정하고, tail을 최상위 요소를 제거한 후 남은 stack으로 설정한다.
3. parentId를 tail에 스택 ID 가져오기를 재귀적으로 호출한 결과로 설정한다.
4. frameId를 head에 프레임 ID 가져오기를 호출한 결과로 설정한다.
5. frameId가 undefined이면 parentId를 반환한다.
6. profilerStack을 ProfilerStack.frameId가 frameId와 같고 ProfilerStack.parentId가 parentId와 같은 새 ProfilerStack으로 설정한다.
7. profilerStack과 ProfilerTrace.stacks에 요소 ID 가져오기를 실행한 결과를 반환한다.

context에 바인딩된 실행 컨텍스트가 주어졌을 때 프레임 ID를 가져오려면 다음 단계를 수행한다.

1. context와 연결된 [= realm =]이 프로파일링 세션과 연결된 렐름과 일치하지 않으면 undefined를 반환한다.
2. instance를 context와 연결된 함수 인스턴스와 같게 설정한다.
3. scriptOrModule을 context와 연결된 ScriptOrModule과 같게 설정한다.
4. |attributedScriptOrModule : ScriptOrModule|을 다음 알고리즘을 실행한 결과와 같게 설정한다.
   1. |scriptOrModule|이 null이 아니면 |scriptOrModule|을 반환한다.
   2. |instance|가 내장 함수 객체이면 |instance|를 호출한 함수를 포함하는 ScriptOrModule을 반환한다.

      위 로직의 목적은 접근할 수 없는 스크립트가 호출한 내장 함수가 추적 데이터에 노출되지 않도록, 해당 함수의 귀속에 그 함수를 호출한 ScriptOrModule을 사용하는 것이다.

      “|instance|를 호출한 함수를 포함하는 ScriptOrModule”은 더 엄밀하게 정의해야 한다. 이를 제공하기 위해 스택에서 ScriptOrModule을 정의하는 최상위 실행 컨텍스트를 활용할 수 있지만, 이는 이상적이지 않다. 이론적으로 내장 함수가 실행 컨텍스트 스택에 대기열로 추가되는 다른 메커니즘이 존재할 수 있으며, 이 경우 귀속은 유효하지 않게 된다.

   3. 그렇지 않으면 null을 반환한다.
5. |attributedScriptOrModule|이 null이면 undefined를 반환한다.
6. |attributedScript : Script|를 |attributedScriptOrModule|.[[\HostDefined]]에서 얻은 [= script =]로 설정한다.
7. |attributedScript|가 [= classic script =]이고 해당 오류 음소거 불리언이 true와 같으면 undefined를 반환한다.

   이 검사는 CORS 교차 출처 응답으로 제공된 교차 출처 스크립트의 스택 프레임을 포함하지 않도록 보장한다. 이 사용 사례를 더 잘 반영하도록 오류 음소거의 이름을 변경하는 것을 고려할 수 있다.

8. frame을 새 ProfilerFrame으로 설정한다.
9. frame의 ProfilerFrame.name을 |instance|와 연결된 함수 인스턴스 이름으로 설정한다.
10. |scriptOrModule|이 null이 아니면:
    1. script를 scriptOrModule.[[\HostDefined]]에서 얻은 스크립트로 설정한다.
    2. resourceString을 script의 기준 URL과 같게 설정한다.
    3. ProfilerFrame.resourceId를 resourceString과 ProfilerTrace.resources에 요소 ID 가져오기를 실행한 결과로 설정한다.
    4. frame의 ProfilerFrame.line을 |script|에서 instance가 정의된 줄의 1부터 시작하는 인덱스로 설정한다.
    5. frame의 ProfilerFrame.column을 |script|에서 instance가 정의된 열의 1부터 시작하는 인덱스로 설정한다.
11. frame과 ProfilerTrace.frames에 요소 ID 가져오기를 실행한 결과를 반환한다.

list에 있는 item의 요소 ID를 가져오려면 다음 단계를 실행한다.

1. list에 item과 구성 요소별로 동일한 요소가 있으면 해당 인덱스를 반환한다.
2. 그렇지 않으면 item을 list의 끝에 추가하고 해당 인덱스를 반환한다.

Profiler 인터페이스

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

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

각 Profiler는 반드시 정확히 하나의 프로파일링 세션과 연결되어야 한다.

sampleInterval 속성은 연결된 프로파일링 세션의 샘플 간격을 DOMHighResTimeStamp로 표현하여 반영해야 한다.

stopped 속성은 프로파일링 세션의 상태가 stopped인 경우에만 true여야 한다.

ProfilerTrace 딕셔너리

      typedef DOMString ProfilerResource;

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

resources 속성은 샘플 수집 알고리즘이 설정한 ProfilerResource 목록을 반환해야 한다.

frames 속성은 샘플 수집 알고리즘이 설정한 ProfilerFrame 목록을 반환해야 한다.

stacks 속성은 샘플 수집 알고리즘이 설정한 ProfilerStack 목록을 반환해야 한다.

samples 속성은 샘플 수집 알고리즘이 설정한 ProfilerSample 목록을 반환해야 한다.

이 표현은 V8 추적 이벤트 형식 및 Gecko 프로파일 형식에서 영감을 얻었으며, 쉽고 효율적으로 직렬화할 수 있도록 설계되었다.

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

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

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

ProfilerInitOptions 딕셔너리

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

ProfilerInitOptions는 다음 필드를 지원해야 한다.

• sampleInterval은 애플리케이션이 원하는 샘플 간격이다. 이 값은 반드시 0보다 크거나 같아야 한다.
• maxBufferSize는 샘플 단위로 나타낸 원하는 샘플 버퍼 크기 제한이다.

문서 정책

이 명세는 프로파일링 기능과 초기화 동작을 제어하기 위해 문서 정책의 구성 지점을 정의한다.

자동화

사용자 에이전트 자동화 및 애플리케이션 테스트를 위해 이 문서는 다음 [[WebDriver]] 확장 명령을 정의한다.