성능 타임라인

이 내용은 [HR-TIME-3]의 Performance 인터페이스를 확장하며, 성능 타임라인에서 성능 메트릭 데이터를 조회할 때 사용하는 성능 관련 속성과 메서드를 포함한다.

WebIDLpartial interface Performance {
  PerformanceEntryList getEntries ();
  PerformanceEntryList getEntriesByType (DOMString type);
  PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
};
typedef sequence<PerformanceEntry> PerformanceEntryList;

PerformanceEntryList는 PerformanceEntry 시퀀스를 나타내며, 개발자에게 자바스크립트 배열에서 제공되는 모든 편의 메서드를 제공한다.

WebIDLdictionary PerformanceObserverCallbackOptions {
  unsigned long long droppedEntriesCount;
};

droppedEntriesCount

옵저버가 관찰 중인 엔트리 타입에서 드롭된 엔트리의 개수를 나타내는 정수. PerformanceObserver의 드롭된 엔트리 필요 여부가 설정된 경우에 해당한다.

observe() 메서드는 사용자 에이전트에게 옵저버를 등록하도록 지시하며, 다음 단계를 실행해야 한다:

1. relevantGlobal을 this의 관련 글로벌 오브젝트로 한다.
2. options의 entryTypes와 type 멤버가 모두 생략된 경우, "TypeError"를 throw한다.
3. options의 entryTypes가 존재하고, 다른 멤버도 존재하면 "TypeError"를 throw한다.
4. this의 옵저버 타입을 다음 단계로 업데이트 또는 확인한다:
   1. this의 옵저버 타입이 "undefined"인 경우:
      1. options의 entryTypes가 존재하면, this의 옵저버 타입을 "multiple"로 설정한다.
      2. options의 type가 존재하면, this의 옵저버 타입을 "single"로 설정한다.
   2. this의 옵저버 타입이 "single"이고 options의 entryTypes가 존재하면, "InvalidModificationError"를 throw한다.
   3. this의 옵저버 타입이 "multiple"이고 options의 type가 존재하면, "InvalidModificationError"를 throw한다.
5. this의 드롭된 엔트리 필요 여부를 true로 설정한다.
6. this의 옵저버 타입이 "multiple"이면, 다음 단계를 실행한다:
   1. entry types를 options의 entryTypes 시퀀스로 한다.
   2. entry types에서 relevantGlobal의 지원되는 엔트리 타입 동결 배열에 포함되지 않은 모든 타입을 제거한다. 사용자 에이전트는 SHOULD 개발자에게 entry types가 수정되었음을 알려야 한다. 예를 들어, 콘솔 경고로 제거된 타입을 알려줄 수 있다.
   3. 결과 entry types 시퀀스가 빈 시퀀스라면, 이 단계들을 중단한다. 사용자 에이전트는 SHOULD 이 단계가 중단되었음을 개발자에게 알려야 한다. 예를 들어, 콘솔 경고가 적절하다.
   4. relevantGlobal의 등록된 성능 옵저버 객체 리스트에 등록된 성능 옵저버 중 옵저버가 this인 것이 있으면, 그 옵션 리스트를 options 하나만 담은 리스트로 바꾼다.
   5. 그렇지 않으면, 등록된 성능 옵저버 객체를 생성해서 relevantGlobal의 등록된 성능 옵저버 객체 리스트에 추가하는데, 옵저버에는 this를, 옵션 리스트에는 options 하나만 담은 리스트를 설정한다.
7. 그렇지 않으면, 다음 단계를 실행한다:
   1. this의 옵저버 타입이 "single"임을 단언한다.
   2. options의 type이 relevantGlobal의 지원되는 엔트리 타입 동결 배열에 포함되지 않으면, 이 단계들을 중단한다. 사용자 에이전트는 SHOULD 이 상황을 개발자에게 알려야 한다. 예를 들어, 콘솔 경고가 적절하다.
   3. relevantGlobal의 등록된 성능 옵저버 객체 리스트에 등록된 성능 옵저버 obs 중 옵저버가 this인 경우:
      1. obs의 옵션 리스트에 PerformanceObserverInit 아이템 currentOptions가 있고, 그 type이 options의 type과 같으면, currentOptions를 options로 교체한다.
      2. 그렇지 않으면, options를 obs의 옵션 리스트에 추가한다.
   4. 그렇지 않으면, 등록된 성능 옵저버 객체를 생성해서 relevantGlobal의 등록된 성능 옵저버 객체 리스트에 추가하는데, 옵저버에는 this를, 옵션 리스트에는 options 하나만 담은 리스트를 설정한다.
   5. options의 buffered 플래그가 설정된 경우:
      1. tuple을 options의 type와 relevantGlobal의 관련 성능 엔트리 튜플로 한다.

      2. tuple의 성능 엔트리 버퍼의 각 entry에 대해:

         1. should add entry에 entry와 options를 인자로 넘겨 true를 반환하면, entry를 옵저버 버퍼에 append한다.
      3. PerformanceObserver 작업 큐에 추가를 relevantGlobal을 인자로 하여 실행한다.

WebIDLdictionary PerformanceObserverInit {
  sequence<DOMString> entryTypes;
  DOMString type;
  boolean buffered;
};

WebIDL[Exposed=(Window,Worker)]
interface PerformanceObserverEntryList {
  PerformanceEntryList getEntries();
  PerformanceEntryList getEntriesByType (DOMString type);
  PerformanceEntryList getEntriesByName (DOMString name, optional DOMString type);
};

takeRecords() 메서드는 this의 옵저버 버퍼의 복사본을 반환하며, this의 옵저버 버퍼도 비워야 한다.

disconnect() 메서드는 다음을 수행해야 한다:

1. this를 등록된 성능 옵저버 객체 리스트에서 제거한다 (관련 글로벌 오브젝트 기준).
2. this의 옵저버 버퍼를 비운다.
3. this의 옵션 리스트를 비운다.

각 글로벌 오브젝트는 연관된 지원되는 엔트리 타입의 동결 배열을 가지며, 이는 레지스트리에서 해당 글로벌 오브젝트가 지원하는 문자열의 시퀀스를 알파벳순으로 정렬한 뒤 FrozenArray 생성으로 초기화한다.

supportedEntryTypes 속성의 getter가 호출되면 다음 단계를 실행한다:

1. globalObject를 환경 설정 오브젝트의 글로벌 오브젝트로 한다.
2. globalObject의 지원되는 엔트리 타입의 동결 배열을 반환한다.

PerformanceEntry 큐에 추가(newEntry)하려면 다음 단계를 실행한다:

1. newEntry의 id가 설정되지 않은 경우:
   1. id를 id 생성 결과값으로 한다.
   2. newEntry의 id에 id를 설정한다.
2. interested observers를 초기에는 빈 PerformanceObserver 객체 집합으로 한다.
3. entryType을 newEntry의 entryType 값으로 한다.
4. relevantGlobal을 newEntry의 관련 글로벌 오브젝트로 한다.
5. relevantGlobal가 연관된 document를 가지는 경우:
   1. newEntry의 navigationId를 relevantGlobal의 연관된 document의 가장 최근 내비게이션의 id 값으로 설정한다.
6. 그렇지 않으면 newEntry의 navigationId를 null로 설정한다.
7. relevantGlobal의 등록된 성능 옵저버 객체 리스트의 각 등록된 성능 옵저버 regObs에 대해:

   1. regObs의 옵션 리스트에 PerformanceObserverInit options가 있고, 그 entryTypes가 entryType을 포함하거나, type가 entryType과 같다면:

      1. should add entry에 newEntry와 options를 넘겨 true면, regObs의 옵저버를 interested observers에 추가한다.
8. interested observers의 각 observer에 대해:
   1. newEntry를 observer의 옵저버 버퍼에 추가한다.
9. tuple을 entryType과 relevantGlobal의 관련 성능 엔트리 튜플로 한다.
10. isBufferFull을 성능 엔트리 버퍼가 가득 찼는지 확인 알고리즘 결과값으로 한다.
11. shouldAdd을 should add entry에 newEntry를 넘긴 결과값으로 한다.
12. isBufferFull이 false이고 shouldAdd이 true이면, tuple의 성능 엔트리 버퍼에 newEntry를 추가한다.
13. PerformanceObserver 작업 큐에 추가를 relevantGlobal을 인자로 실행한다.

내비게이션 PerformanceEntry 큐에 추가(newEntry)하려면 다음 단계를 실행한다:

1. id를 id 생성 결과값으로 한다.
2. relevantGlobal을 newEntry의 관련 글로벌 오브젝트로 한다.
3. newEntry의 id를 id로 설정한다.
4. newEntry의 navigationId를 id로 설정한다.
5. relevantGlobal가 연관된 document를 가지는 경우:
   1. relevantGlobal의 연관된 document의 가장 최근 내비게이션을 newEntry로 설정한다.
6. PerformanceEntry 큐에 추가를 newEntry를 인자로 실행한다.

PerformanceObserver 작업 큐에 추가를 요청받으면, relevantGlobal을 인자로 다음 단계를 실행한다:

1. relevantGlobal의 성능 옵저버 작업 큐 플래그가 설정되어 있으면, 이 단계들을 종료한다.
2. relevantGlobal의 성능 옵저버 작업 큐 플래그를 설정한다.
3. 작업 큐에 추가를 실행하는데, 다음 하위 단계를 포함한다. 큐에 추가된 작업의 작업 소스는 성능 타임라인 작업 소스이다.
   1. relevantGlobal의 성능 옵저버 작업 큐 플래그를 해제한다.
   2. notifyList를 relevantGlobal의 등록된 성능 옵저버 객체 리스트의 복사본으로 한다.
   3. notifyList의 각 등록된 성능 옵저버 객체 registeredObserver에 대해 다음 단계 실행:
      1. po를 registeredObserver의 옵저버로 한다.
      2. entries를 po의 옵저버 버퍼의 복사본으로 한다.
      3. entries가 비어 있으면 return.
      4. po의 옵저버 버퍼를 비운다.
      5. observerEntryList를 새로운 PerformanceObserverEntryList로 생성하며, 엔트리 리스트를 entries로 설정한다.
      6. droppedEntriesCount를 null로 한다.
      7. po의 드롭된 엔트리 필요 여부가 설정되어 있으면 다음 단계 실행:
         1. droppedEntriesCount를 0으로 설정한다.
         2. registeredObserver의 옵션 리스트의 각 PerformanceObserverInit item에 대해:
            1. item의 type 또는 entryTypes에 나타나는 각 DOMString entryType에 대해:
               1. map을 relevantGlobal의 성능 엔트리 버퍼 맵로 한다.
               2. tuple을 map에서 entryType을 키로 하여 얻은 값으로 한다.
               3. droppedEntriesCount에 tuple의 드롭된 엔트리 카운트를 더한다.
         3. po의 드롭된 엔트리 필요 여부를 false로 설정한다.
      8. callbackOptions을 PerformanceObserverCallbackOptions로 생성하며, droppedEntriesCount를 droppedEntriesCount가 null이 아니면 해당 값으로 하고, 아니면 설정하지 않는다.
      9. 콜백 함수 호출을 실행하는데, po의 옵저버 콜백에 « observerEntryList, po, callbackOptions », "report", po를 전달한다.

성능 타임라인 작업 큐는 낮은 우선순위 큐로, 성능 모니터링 코드의 영향을 최소화하기 위해 사용자 에이전트가 가능하다면 유휴 시간에 처리해야 한다.

선택적 name과 type으로 이름과 타입으로 버퍼 맵 필터링 알고리즘을 실행하면 다음 단계를 따른다:

1. result를 초기에는 빈 리스트로 한다.
2. map을 성능 엔트리 버퍼 맵으로 하고, 이는 관련 글로벌 오브젝트에 연결되어 있다(this 기준).
3. tuple list를 빈 리스트로 한다.
4. type이 null이 아니면, map에서 type을 키로 하여 얻은 값을 tuple list에 추가한다. 그렇지 않으면 map의 값을 get the values로 tuple list에 할당한다.
5. tuple list의 각 tuple에 대해 다음 단계 실행:
   1. buffer를 tuple의 성능 엔트리 버퍼로 한다.
   2. tuple의 availableFromTimeline이 false면, 다음 tuple로 이동한다.
   3. entries를 이름과 타입으로 버퍼 필터링 알고리즘을 buffer, name, type으로 실행한 결과로 한다.
   4. entries의 각 entry를 result에 추가한다.
6. results의 엔트리들을 startTime 기준으로 시간순으로 정렬한다.
7. result를 반환한다.

이름과 타입으로 버퍼 필터링 알고리즘을 buffer, name, type을 인자로 실행하면 다음 단계를 따른다:

1. result를 초기에는 빈 리스트로 한다.
2. buffer의 각 PerformanceEntry entry에 대해 다음 단계 실행:
   1. type이 null이 아니고, type이 entry의 entryType 속성과 동일하지 않으면 다음 entry로 이동한다.
   2. name이 null이 아니고, name이 entry의 name 속성과 동일하지 않으면 다음 entry로 이동한다.
   3. entry를 result에 추가한다.
3. results의 엔트리들을 startTime 기준으로 시간순으로 정렬한다.
4. result를 반환한다.

성능 엔트리 버퍼가 가득 찼는지 확인 알고리즘을 tuple을 인자로 실행하면 다음 단계를 따른다:

1. num current entries를 tuple의 성능 엔트리 버퍼의 크기로 설정한다.
2. num current entries가 tuples의 maxBufferSize보다 작으면 false를 반환한다.
3. tuple의 드롭된 엔트리 카운트를 1 증가시킨다.
4. true를 반환한다.

id 생성을 PerformanceEntry entry에 요청받으면 다음 단계를 실행한다:

1. relevantGlobal을 entry의 관련 글로벌 오브젝트로 한다.
2. relevantGlobal의 마지막 성능 엔트리 ID를 사용자 에이전트가 선택한 작은 숫자만큼 증가시킨다.
3. relevantGlobal의 마지막 성능 엔트리 ID를 반환한다.

사용자 에이전트는 마지막 성능 엔트리 ID를 매번 작은 랜덤 정수만큼 증가시킬 수 있다. 모든 글로벌 오브젝트의 마지막 성능 엔트리 ID를 하나의 글로벌 랜덤 정수로 증가시키면 교차 출처 정보 노출이 발생할 수 있으므로 반드시 피해야 한다.