User Timing 레벨 2

W3C 권고안

이 버전:
https://www.w3.org/TR/2019/REC-user-timing-2-20190226/
최신 공개 버전:
https://www.w3.org/TR/user-timing-2/
User Timing의 최신 버전:
https://www.w3.org/TR/user-timing/
최신 에디터 드래프트:
https://w3c.github.io/user-timing/
이전 버전:
https://www.w3.org/TR/2019/PR-user-timing-2-20190110/
테스트 스위트:
https://wpt.fyi/results/user-timing
구현 보고서:
https://wpt.fyi/results/user-timing
에디터:
(Google)
이전 에디터:
Jatinder Mann (Microsoft Corp.) (2014년 2월까지)
Zhiheng Wang (Google Inc.) (2013년 7월까지)
Anderson Quach (Microsoft Corp.) (2011년 3월까지)
참여하기:
GitHub w3c/user-timing
버그 제보
커밋 내역
풀 리퀘스트
구현:
User Timing 사용 가능 여부

출판 이후 보고된 오류 또는 이슈는 정오표를 확인해 주세요.

또한 번역본도 참고하세요.


요약

이 명세는 웹 개발자가 애플리케이션의 성능을 측정할 수 있도록 고정밀 타임스탬프에 접근하는 인터페이스를 정의합니다.

문서 현황

이 섹션은 출판 시점의 문서 상태를 설명합니다. 다른 문서가 이 문서를 대체할 수 있습니다. 현재 W3C 발행물 목록과 이 기술 보고서의 최신 판은 W3C 기술 보고서 색인 https://www.w3.org/TR/에서 확인할 수 있습니다.

User Timing 레벨 2는 [USER-TIMING]의 첫 번째 버전을 대체하기 위해 만들어졌으며 다음을 포함합니다:

이 문서는 Web Performance Working Group에서 권고안으로 발행되었습니다.

이 명세에 대한 논의는 GitHub Issues를 통해 진행하는 것이 권장됩니다. 또는 메일링 리스트로 의견을 보낼 수 있습니다. public-web-perf@w3.org (아카이브) 제목의 시작에 [UserTiming]을 추가해 주세요.

작업 그룹의 구현 보고서도 참고하시기 바랍니다.

이 문서는 W3C 회원, 소프트웨어 개발자, 다른 W3C 그룹과 관련자에 의해 검토되었으며, 디렉터의 승인 아래 W3C 권고안으로 인정받았습니다. 안정적인 문서로서 참고자료로 사용하거나 다른 문서에서 인용할 수 있습니다. W3C의 역할은 권고안에 주목하고 널리 보급을 촉진하는 것입니다. 이는 웹의 기능성과 상호운용성을 강화합니다.

이 문서는 W3C 특허 정책에 따라 운영되는 그룹에서 작성되었습니다. W3C특허 공개 목록을 유지합니다. 해당 그룹 산출물과 관련하여 제출된 특허 공개 목록을 확인할 수 있으며, 특허 공개 방법도 안내되어 있습니다. 자신이 필수적 권리를 포함한다고 믿는 특허를 알고 있는 경우, W3C 특허 정책 6항에 따라 정보를 공개해야 합니다.

이 문서는 2018년 2월 1일 W3C 프로세스 문서의 적용을 받습니다.

1. 소개

이 섹션은 비규범적입니다.

웹 개발자는 애플리케이션의 성능 특성을 평가하고 이해할 수 있는 능력이 필요합니다. JavaScript [ECMA-262]는 Date.now() 메서드를 통해 현재 타임스탬프를 가져와 애플리케이션 지연을 측정할 수 있는 메커니즘을 제공하지만, 이 타임스탬프의 정밀도는 사용자 에이전트에 따라 다릅니다.

이 문서는 PerformanceMarkPerformanceMeasure 인터페이스, 그리고 Performance 인터페이스의 확장을 정의하여, 개발자가 애플리케이션 성능 특성을 더 잘 측정할 수 있도록 높은 정밀도의 단조 증가 타임스탬프를 제공합니다.

아래 스크립트는 개발자가 이 문서에서 정의된 인터페이스를 사용하여 개발자 스크립트와 관련된 타이밍 데이터를 얻는 방법을 보여줍니다.

async function run() {
  performance.mark("startTask1");
  await doTask1(); // 개발자 코드 일부
  performance.mark("endTask1");

  performance.mark("startTask2");
  await doTask2(); // 개발자 코드 일부
  performance.mark("endTask2");

  // 로그 출력
  const entries = performance.getEntriesByType("mark");
  for (const entry of entries) {
    console.table(entry.toJSON());
  }
}
run();
참고

[PERFORMANCE-TIMELINE-2]는 기록된 메트릭을 가져오는 두 가지 메커니즘을 정의합니다: getEntries()getEntriesByType() 메서드, 그리고 PerformanceObserver 인터페이스입니다. 전자는 특정 이름의 메트릭을 한 번에 가져오고 싶을 때 적합하며, 후자는 새로운 메트릭이 사용 가능해질 때 알림을 받고 싶을 때 최적화되어 있습니다.

2. 적합성

비규범적으로 표시된 섹션뿐만 아니라, 이 명세의 모든 작성 지침, 다이어그램, 예제, 참고 사항도 비규범적입니다. 그 외의 모든 내용은 규범적입니다.

MAYMUST라는 키워드는 [RFC2119]에서 설명한 대로 해석되어야 합니다.

일부 적합성 요건은 속성, 메서드 또는 객체에 대한 요구사항으로 표현됩니다. 이러한 요구사항은 사용자 에이전트에 대한 요구사항으로 해석되어야 합니다.

이 명세의 IDL 조각들은 MUST Web IDL 명세에서 설명한 대로 적합한 IDL 조각에 대해 요구되는 것으로 해석되어야 합니다. [WEBIDL]

3. User Timing

3.1 Performance 인터페이스 확장

Performance 인터페이스는 [HR-TIME-2]에 정의되어 있습니다.

partial interface Performance {
    void mark(DOMString markName);
    void clearMarks(optional DOMString markName);
    void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark);
    void clearMeasures(optional DOMString measureName);
};

3.1.1 mark() 메서드

이름(“마크”)과 함께 타임스탬프를 저장합니다. 다음 단계들을 필수로 실행해야 합니다:

  1. 글로벌 객체Window 객체이고 markNamePerformanceTiming 인터페이스 내 읽기 전용 속성과 동일한 이름을 사용할 경우, throw SyntaxError를 발생시킵니다.
  2. 새로운 PerformanceMark 객체(entry)를 생성합니다.
  3. entryname 속성을 markName으로 설정합니다.
  4. entryentryType 속성을 DOMString "mark"로 설정합니다.
  5. entrystartTime 속성을 Performance 객체의 now() 메서드가 반환하는 값으로 설정합니다.
  6. entryduration 속성을 0으로 설정합니다.
  7. Queue entry를 실행합니다.
  8. entryperformance entry buffer에 추가합니다.
  9. undefined를 반환합니다.

3.1.2 clearMarks() 메서드

저장된 이름의 타임스탬프를 제거합니다. 다음 단계들을 필수로 실행해야 합니다:

  1. markName이 생략된 경우, PerformanceMark 객체를 performance entry buffer에서 모두 제거합니다.
  2. 그 외에는 PerformanceMark 객체 중 namemarkName과 일치하는 것을 performance entry buffer에서 모두 제거합니다.
  3. undefined를 반환합니다.

3.1.3 measure() 메서드

두 마크 사이의 DOMHighResTimeStamp 지속 시간을 이름과 함께 저장합니다(“측정”). 다음 단계들을 필수로 실행해야 합니다:

  1. end time0으로 설정합니다.
  2. endMark가 생략된 경우 end timePerformance 객체의 now() 메서드가 반환하는 값으로 설정합니다. 그렇지 않으면:
    1. endMarkPerformanceTiming 인터페이스의 읽기 전용 속성과 동일하다면, convert a name to a timestamp 알고리즘을 nameendMark 값을 넣어 실행한 결과를 end time으로 설정합니다.
    2. 그 외에는 PerformanceMark 객체 중 nameendMark와 일치하는 가장 최근 항목의 startTime 값을 end time으로 설정합니다. 일치하는 항목이 없으면 throw SyntaxError를 발생시킵니다.
  3. startMark가 생략된 경우 start time0으로 설정합니다. 그렇지 않으면:
    1. startMarkPerformanceTiming 인터페이스의 읽기 전용 속성과 동일하다면, convert a name to a timestamp 알고리즘을 namestartMark 값을 넣어 실행한 결과를 start time으로 설정합니다.
    2. 그 외에는 PerformanceMark 객체 중 namestartMark와 일치하는 가장 최근 항목의 startTime 값을 start time으로 설정합니다. 일치하는 항목이 없으면 throw SyntaxError를 발생시킵니다.
  4. 새로운 PerformanceMeasure 객체(entry)를 생성합니다.
  5. entryname 속성을 measureName으로 설정합니다.
  6. entryentryType 속성을 DOMString "measure"로 설정합니다.
  7. entrystartTime 속성을 start time으로 설정합니다.
  8. entryduration 속성을 start time부터 end time까지의 지속 시간으로 설정합니다. 결과값은 음수일 수도 있습니다.
  9. Queue entry를 실행합니다.
  10. entryperformance entry buffer에 추가합니다.
  11. undefined를 반환합니다.

3.1.4 clearMeasures() 메서드

저장된 이름의 타임스탬프를 제거합니다. 다음 단계들을 필수로 실행해야 합니다:

  1. measureName이 생략된 경우, PerformanceMeasure 객체를 performance entry buffer에서 모두 제거합니다.
  2. 그 외에는 PerformanceMeasure 객체 중 namemeasureName과 일치하는 것을 performance entry buffer에서 모두 제거합니다.
  3. undefined를 반환합니다.

3.2 PerformanceMark 인터페이스

PerformanceMark 인터페이스는 performance.mark 메서드로 생성된 마크를 Performance Timeline에 노출합니다.

[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
};

PerformanceMark 인터페이스는 PerformanceEntry 인터페이스의 다음 속성을 확장합니다:

name 속성은 해당 마크의 이름을 반환해야 합니다.

entryType 속성은 DOMString "mark"를 반환해야 합니다.

startTime 속성은 해당 마크의 시간값을 DOMHighResTimeStamp로 반환해야 합니다.

duration 속성은 DOMHighResTimeStamp0 값을 반환해야 합니다.

3.3 PerformanceMeasure 인터페이스

PerformanceMeasure 인터페이스는 performance.measure 메서드로 생성된 측정값을 Performance Timeline에 노출합니다.

[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
};

PerformanceMeasure 인터페이스는 PerformanceEntry 인터페이스의 다음 속성을 확장합니다:

name 속성은 해당 측정값의 이름을 반환해야 합니다.

entryType 속성은 DOMString "measure"를 반환해야 합니다.

startTime 속성은 해당 측정값의 시작 마크를 DOMHighResTimeStamp로 반환해야 합니다.

duration 속성은 해당 측정의 지속 시간을 DOMHighResTimeStamp로 반환해야 합니다.

4. 처리

User Timing API를 구현하는 사용자 에이전트는 다음 단계를 수행해야 합니다:

  1. register a performance entry type 알고리즘을 "mark"를 입력값으로 실행합니다.
  2. register a performance entry type 알고리즘을 "measure"를 입력값으로 실행합니다.

4.1 nametimestamp로 변환

timestamp로 name을 변환하려면, namePerformanceTiming 인터페이스의 읽기 전용 속성일 때, 다음 단계를 실행합니다:

  1. 글로벌 객체Window 객체가 아니면, throw SyntaxError를 발생시킵니다.
  2. namenavigationStart이면 0을 반환합니다.
  3. startTimePerformanceTiming 인터페이스의 navigationStart 값으로 설정합니다.
  4. endTimePerformanceTiming 인터페이스의 name 값으로 설정합니다.
  5. endTime0이면 throw InvalidAccessError를 발생시킵니다.
  6. endTime에서 startTime을 뺀 결과를 반환합니다.
참고

PerformanceTiming 인터페이스는 [NAVIGATION-TIMING]에 정의되었으며, 현재는 폐지된 것으로 간주됩니다. PerformanceTiming 인터페이스의 이름 사용은 이전 버전과의 호환성을 위해 지원되며, 향후 [NAVIGATION-TIMING-2]에 정의된 PerformanceNavigationTiming 인터페이스(또는 기타 인터페이스)의 이름으로 이 기능을 확장할 계획은 없습니다.

5. 개인정보 및 보안

이 섹션은 비규범적입니다.

이 명세에서 정의된 인터페이스는 특정 JavaScript 활동의 민감한 타이밍 정보를 노출할 수 있습니다. 고해상도 타이밍 정보를 노출함에 있어 개인정보 및 보안 고려사항은 [HR-TIME-2]를 참고하세요.

웹 플랫폼은 페이지에 포함된 어떠한 스크립트든 동일한 페이지 내의 다른 스크립트와 동일한 접근 권한을 가지도록 설계되었으므로, 이 명세에서 정의한 인터페이스는 기록된 타이밍 정보의 기록 또는 조회에 아무런 제약을 두지 않습니다. 즉, 페이지에 포함된 어떤 스크립트가 기록한 user timing 마크나 측정값은 동일 페이지에서 실행되는 다른 스크립트가 출처에 관계없이 읽을 수 있습니다.

A. 감사의 글

이 작업에 기여해 준 James Simonsen, Jason Weber, Nic Jansma, Philippe Le Hegaret, Karen Anderson, Steve Souders, Sigbjorn Vik, Todd Reifsteck, 그리고 Tony Gentilcore 에게 감사드립니다.

B. 참고문헌

B.1 규범적 참고문헌

[HR-TIME-2]
고해상도 시간(Level 2). Ilya Grigorik; James Simonsen; Jatinder Mann. W3C. 2018년 3월 1일. W3C Candidate Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[HTML51]
HTML 5.1 2nd Edition. Steve Faulkner; Arron Eicholz; Travis Leithead; Alex Danilo. W3C. 2017년 10월 3일. W3C Recommendation. URL: https://www.w3.org/TR/html51/
[NAVIGATION-TIMING]
Navigation Timing. Zhiheng Wang. W3C. 2012년 12월 17일. W3C Recommendation. URL: https://www.w3.org/TR/navigation-timing/
[PERFORMANCE-TIMELINE-2]
Performance Timeline Level 2. Ilya Grigorik. W3C. 2019년 1월 10일. W3C Working Draft. URL: https://www.w3.org/TR/performance-timeline-2/
[RFC2119]
RFC에서 요구 수준을 나타내는 키워드. S. Bradner. IETF. 1997년 3월. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[WEBIDL]
Web IDL. Cameron McCormack; Boris Zbarsky; Tobie Langel. W3C. 2016년 12월 15일. W3C Editor's Draft. URL: https://heycam.github.io/webidl/
[WORKERS]
Web Workers. Ian Hickson. W3C. 2015년 9월 24일. W3C Working Draft. URL: https://www.w3.org/TR/workers/

B.2 비규범적 참고문헌

[ECMA-262]
ECMAScript 언어 명세. Ecma International. URL: https://tc39.github.io/ecma262/
[NAVIGATION-TIMING-2]
Navigation Timing Level 2. Ilya Grigorik; Tobin Titus; Jatinder Mann; Arvind Jain. W3C. 2018년 11월 30일. W3C Working Draft. URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING]
User Timing. Jatinder Mann; Zhiheng Wang; Anderson Quach. W3C. 2013년 12월 12일. W3C Recommendation. URL: https://www.w3.org/TR/user-timing/