User Timing

비규범적으로 표시된 절뿐만 아니라, 이 명세의 모든 작성 지침, 다이어그램, 예제 및 참고는 비규범적입니다. 이 명세의 그 밖의 모든 내용은 규범적입니다.

이 문서의 핵심 단어 MAY와 MUST는 여기에 표시된 것처럼 모두 대문자로 나타날 때, 그리고 그럴 때에만, BCP 14 [RFC2119] [RFC8174]에 설명된 대로 해석해야 합니다.

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

이 명세의 IDL 조각은 Web IDL 명세에 설명된 것처럼, 적합한 IDL 조각에 필요한 것으로 해석해야 MUST 합니다. [WEBIDL]

Performance 인터페이스와 DOMHighResTimeStamp는 [HR-TIME-2]에서 정의됩니다. PerformanceEntry 인터페이스는 [PERFORMANCE-TIMELINE-2]에서 정의됩니다.

WebIDLdictionary PerformanceMarkOptions {
    any detail;
    DOMHighResTimeStamp startTime;
};

dictionary PerformanceMeasureOptions {
    any detail;
    (DOMString or DOMHighResTimeStamp) start;
    DOMHighResTimeStamp duration;
    (DOMString or DOMHighResTimeStamp) end;
};

partial interface Performance {
    PerformanceMark mark(DOMString markName, optional PerformanceMarkOptions markOptions = {});
    undefined clearMarks(optional DOMString markName);
    PerformanceMeasure measure(DOMString measureName, optional (DOMString or PerformanceMeasureOptions) startOrMeasureOptions = {}, optional DOMString endMark);
    undefined clearMeasures(optional DOMString measureName);
};

연결된 이름과 함께 타임스탬프("mark")를 저장합니다. 이 메서드는 다음 단계를 실행해야 MUST 합니다.

PerformanceMark 생성자를 실행하고, 새로 생성된 객체를 entry로 둡니다.
entry를 큐에 넣습니다.
entry를 performance entry buffer에 추가합니다.
entry를 반환합니다.

detail: mark에 포함될 메타데이터.
startTime: mark 시간으로 사용할 타임스탬프.

연결된 이름을 가진 저장된 타임스탬프를 제거합니다. 이 메서드는 다음 단계를 실행해야 MUST 합니다.

markName이 생략된 경우, PerformanceMark 객체를 모두 performance entry buffer에서 제거합니다.
그렇지 않으면, PerformanceMark 객체 중 performance entry buffer에 나열되어 있고 그 name이 markName인 객체를 모두 제거합니다.
undefined를 반환합니다.

두 mark 사이의 DOMHighResTimeStamp 지속 시간과 연결된 이름("measure")을 저장합니다. 이 메서드는 다음 단계를 실행해야 MUST 합니다.

startOrMeasureOptions가 PerformanceMeasureOptions 객체이고 start, end, duration 및 detail 중 적어도 하나가 존재하면, 다음 검사를 실행합니다.
1. endMark가 주어진 경우, throw a TypeError.
2. startOrMeasureOptions의 start 및 end 멤버가 둘 다 생략된 경우, throw a TypeError.
3. startOrMeasureOptions의 start, duration 및 end 멤버가 모두 존재하면, throw a TypeError.
end time을 다음과 같이 계산합니다.
1. endMark가 주어진 경우, end time을 endMark를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
2. 그렇지 않고, startOrMeasureOptions가 PerformanceMeasureOptions 객체이며, 그 end 멤버가 존재하면, end time을 startOrMeasureOptions의 end를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
3. 그렇지 않고, startOrMeasureOptions가 PerformanceMeasureOptions 객체이며, 그 start 및 duration 멤버가 둘 다 존재하면:
  1. start를 start를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
  2. duration을 duration을 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
  3. end time을 start 더하기 duration으로 둡니다.
4. 그렇지 않으면, end time을 Performance 객체의 now() 메서드가 반환할 값으로 둡니다.
start time을 다음과 같이 계산합니다.
1. startOrMeasureOptions가 PerformanceMeasureOptions 객체이고, 그 start 멤버가 존재하면, start time을 startOrMeasureOptions의 start를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
2. 그렇지 않고, startOrMeasureOptions가 PerformanceMeasureOptions 객체이며, 그 duration 및 end 멤버가 둘 다 존재하면:
  1. duration을 duration을 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
  2. end를 end를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
  3. start time을 end 빼기 duration으로 둡니다.
3. 그렇지 않고, startOrMeasureOptions가 DOMString이면, start time을 startOrMeasureOptions를 전달하여 mark를 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
4. 그렇지 않으면, start time을 0으로 둡니다.
PerformanceMeasure 객체 (entry)를 this의 관련 렘으로 새로 만듭니다.
entry의 name 속성을 measureName으로 설정합니다.
entry의 entryType 속성을 DOMString "measure"로 설정합니다.
entry의 startTime 속성을 start time으로 설정합니다.
entry의 duration 속성을 start time부터 end time까지의 지속 시간으로 설정합니다. 그 결과 지속 시간 값은 음수일 수 MAY 있습니다.
entry의 detail 속성을 다음과 같이 설정합니다.
1. startOrMeasureOptions가 PerformanceMeasureOptions 객체이고 startOrMeasureOptions의 detail 멤버가 존재하면:
  1. record를 startOrMeasureOptions의 detail에 StructuredSerialize 알고리즘을 호출한 결과로 둡니다.
  2. entry의 detail을 record 및 현재 렘에 StructuredDeserialize 알고리즘을 호출한 결과로 설정합니다.
2. 그렇지 않으면, 이를 null로 설정합니다.
entry를 큐에 넣습니다.
entry를 performance entry buffer에 추가합니다.
entry를 반환합니다.

detail: measure에 포함될 메타데이터.
start: 시작 시간으로 사용할 타임스탬프 또는 시작 mark로 사용할 문자열.
duration: 시작 시간과 종료 시간 사이의 지속 시간.
end: 종료 시간으로 사용할 타임스탬프 또는 종료 mark로 사용할 문자열.

연결된 이름을 가진 저장된 타임스탬프를 제거합니다. 이 메서드는 다음 단계를 실행해야 MUST 합니다.

measureName이 생략된 경우, PerformanceMeasure 객체를 모두 performance entry buffer에서 제거합니다.
그렇지 않으면, PerformanceMeasure 객체 중 performance entry buffer에 나열되어 있고 그 name이 measureName인 객체를 모두 제거합니다.
undefined를 반환합니다.

PerformanceMark 인터페이스는 Performance 인터페이스의 mark() 메서드를 통해 생성된 mark도 Performance Timeline에 노출합니다.

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMark : PerformanceEntry {
  constructor(DOMString markName, optional PerformanceMarkOptions markOptions = {});
  readonly attribute any detail;
};

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

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

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

startTime 속성은 mark의 시간 값을 가진 DOMHighResTimeStamp를 반환해야 합니다.

duration 속성은 값이 0인 DOMHighResTimeStamp를 반환해야 합니다.

PerformanceMark 인터페이스에는 다음 추가 속성이 포함됩니다.

detail 속성은 설정된 값을 반환해야 합니다(이는 PerformanceMarkOptions 딕셔너리에서 복사됩니다).

PerformanceMark 생성자는 다음 단계를 실행해야 합니다.

현재 전역 객체가 Window 객체이고 markName이 PerformanceTiming 인터페이스의 읽기 전용 속성과 같은 이름을 사용하는 경우, throw a SyntaxError.
PerformanceMark 객체 (entry)를 현재 전역 객체의 렘으로 새로 만듭니다.
entry의 name 속성을 markName으로 설정합니다.
entry의 entryType 속성을 DOMString "mark"로 설정합니다.
entry의 startTime 속성을 다음과 같이 설정합니다.
1. markOptions의 startTime 멤버가 존재하면:
  1. markOptions의 startTime이 음수이면, TypeError를 throw합니다.
  2. 그렇지 않으면, entry의 startTime을 markOptions의 startTime 값으로 설정합니다.
2. 그렇지 않으면, 이를 Performance 객체의 now() 메서드가 반환할 값으로 설정합니다.
entry의 duration 속성을 0으로 설정합니다.
markOptions의 detail이 null이면, entry의 detail을 null로 설정합니다.
그렇지 않으면:
1. record를 markOptions의 detail에 StructuredSerialize 알고리즘을 호출한 결과로 둡니다.
2. entry의 detail을 record 및 현재 렘에 StructuredDeserialize 알고리즘을 호출한 결과로 설정합니다.

PerformanceMeasure 인터페이스는 Performance 인터페이스의 measure() 메서드를 통해 생성된 measure도 Performance Timeline에 노출합니다.

WebIDL[Exposed=(Window,Worker)]
interface PerformanceMeasure : PerformanceEntry {
  readonly attribute any detail;
};

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

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

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

startTime 속성은 measure의 시작 mark를 가진 DOMHighResTimeStamp를 반환해야 합니다.

duration 속성은 measure의 지속 시간을 가진 DOMHighResTimeStamp를 반환해야 합니다.

PerformanceMeasure 인터페이스에는 다음 추가 속성이 포함됩니다.

detail 속성은 설정된 값을 반환해야 합니다(이는 PerformanceMeasureOptions 딕셔너리에서 복사됩니다).

참고

User Timing API를 구현하는 사용자 에이전트는 supportedEntryTypes에 "mark"와 "measure"를 포함해야 합니다. 이를 통해 개발자는 User Timing 지원 여부를 감지할 수 있습니다.

DOMString 또는 DOMHighResTimeStamp인 mark가 주어졌을 때, mark를 timestamp로 변환하려면 다음 단계를 실행합니다.

mark가 DOMString이고 PerformanceTiming 인터페이스의 읽기 전용 속성과 같은 이름을 가지면, end time을 name을 mark의 값으로 설정하여 name을 timestamp로 변환 알고리즘을 실행한 결과로 둡니다.
그렇지 않고, mark가 DOMString이면, end time을 performance entry buffer 안의 PerformanceMark 객체 중 그 name이 mark인 가장 최근 항목의 startTime 속성 값으로 둡니다. 일치하는 항목을 찾을 수 없으면, throw a SyntaxError.
그렇지 않고, mark가 DOMHighResTimeStamp이면:
1. mark가 음수이면, TypeError를 throw합니다.
2. 그렇지 않으면, end time을 mark로 둡니다.

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

전역 객체가 Window 객체가 아니면, throw a TypeError.
name이 navigationStart이면, 0을 반환합니다.
startTime을 PerformanceTiming 인터페이스의 navigationStart 값으로 둡니다.
endTime을 PerformanceTiming 인터페이스의 name 값으로 둡니다.
endTime이 0이면, throw an InvalidAccessError.
endTime에서 startTime을 뺀 결과를 반환합니다.

참고

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

개발자는 공통 타이밍을 표시하기 위해 다음 권장 mark 이름을 사용하도록 권장됩니다. 사용자 에이전트는 이러한 이름의 사용이 그 설명에 적절하거나 일관적인지 검증하지 않습니다.

참고

이러한 권장 mark 이름을 추가하면 성능 도구가 사이트에 맞게 안내를 조정하는 데 도움이 될 수 있습니다. 또한 이러한 mark 이름은 실제 사용자 모니터링 제공자와 사용자 에이전트가 애플리케이션 성능에 관한 웹 개발자 신호를 대규모로 수집하고, 사이트별 작업 없이도 이 정보를 개발자에게 표시하는 데 도움이 될 수 있습니다.

"mark_fully_loaded"

개발자가 자신의 애플리케이션에서 표시한, 페이지가 완전히 로드된 것으로 간주되는 시간.

참고

이 예제에서 페이지는 로딩 시 채팅 위젯, 검색 상자, 뉴스피드를 비동기적으로 초기화합니다. 완료되면 "mark_fully_loaded" mark 이름을 통해 실험실 도구와 분석 제공자가 타이밍을 자동으로 표시할 수 있습니다.

예제 3

window.addEventListener("load", (event) => {
  Promise.all([
    loadChatWidget(),
    initializeSearchAutocomplete(),
    initializeNewsfeed()]).then(() => {
      performance.mark('mark_fully_loaded');
  });
});

"mark_fully_visible"

개발자가 자신의 애플리케이션에서 표시한, 페이지가 최종 사용자에게 완전히 보이는 것으로 간주되는 시간.

"mark_interactive"

개발자가 자신의 애플리케이션에서 표시한, 페이지가 최종 사용자에게 상호작용 가능한 것으로 간주되는 시간.

"mark_feature_usage"

성능에 영향을 줄 수 있는 기능의 사용을 표시하여 도구와 분석이 이를 고려할 수 있게 합니다. detail 메타데이터는 다음을 포함하여 기능에 관한 유용한 정보를 담을 수 있습니다.

feature: 사용된 기능의 이름.
framework: 해당하는 경우, JavaScript 프레임워크, 콘텐츠 관리 시스템 또는 전자상거래 플랫폼처럼 그 기능이 의도한 기반 프레임워크.

참고

이 예제에서는 FancyJavaScriptFramework용 ImageOptimizationComponent가 최적 성능을 위해 이미지 크기를 조정하는 데 사용됩니다. 코드는 실험실 도구와 분석이 이 기능의 사용 여부와 성능 개선에 도움이 되었는지를 측정할 수 있도록 이 기능의 사용을 기록합니다.

예제 4

performance.mark('mark_feature_usage', {
  'detail': {
    'feature': 'ImageOptimizationComponent',
    'framework': 'FancyJavaScriptFramework'
  }
})

[HR-TIME-2]: High Resolution Time Level 2. Ilya Grigorik. W3C. 2019년 11월 21일. W3C Recommendation. URL: https://www.w3.org/TR/hr-time-2/
[HTML]: HTML Standard. Anne van Kesteren; Domenic Denicola; Dominic Farolino; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[infra]: Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
[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. Nicolas Pena Moreno. W3C. 2025년 5월 21일. CRD. URL: https://www.w3.org/TR/performance-timeline/
[RFC2119]: Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. 1997년 3월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. 2017년 5월. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[WEBIDL]: Web IDL Standard. Edgar Chen; Timothy Gu. WHATWG. Living Standard. URL: https://webidl.spec.whatwg.org/

[ECMA-262]: ECMAScript Language Specification. Ecma International. URL: https://tc39.es/ecma262/multipage/
[NAVIGATION-TIMING-2]: Navigation Timing Level 2. Yoav Weiss; Noam Rosenthal. W3C. 2026년 2월 25일. W3C Working Draft. URL: https://www.w3.org/TR/navigation-timing-2/
[USER-TIMING-2]: User Timing Level 2. Ilya Grigorik. W3C. 2019년 2월 26일. W3C Recommendation. URL: https://www.w3.org/TR/user-timing-2/

User Timing

초록

이 문서의 상태

1. 소개

2. 적합성

3. User Timing

3.1 `Performance` 인터페이스에 대한 확장

3.1.1 `mark()` 메서드

3.1.1.1 `PerformanceMarkOptions` 딕셔너리

3.1.2 `clearMarks()` 메서드

3.1.3 `measure()` 메서드

3.1.3.1 `PerformanceMeasureOptions` 딕셔너리

3.1.4 `clearMeasures()` 메서드

3.2 `PerformanceMark` 인터페이스

3.2.1 `PerformanceMark` 생성자

3.3 `PerformanceMeasure` 인터페이스

4. 처리

4.1 `mark`를 `timestamp`로 변환

4.2 `name`을 `timestamp`로 변환

5. 권장 mark 이름

6. 개인정보 보호와 보안

A. 감사의 말

B. 참고 문헌

B.1 규범 참고 문헌

B.2 정보 참고 문헌

User Timing

초록

이 문서의 상태

1. 소개

2. 적합성

3. User Timing

3.1 Performance 인터페이스에 대한 확장

3.1.1 mark() 메서드

3.1.1.1 PerformanceMarkOptions 딕셔너리

3.1.2 clearMarks() 메서드

3.1.3 measure() 메서드

3.1.3.1 PerformanceMeasureOptions 딕셔너리

3.1.4 clearMeasures() 메서드

3.2 PerformanceMark 인터페이스

3.2.1 PerformanceMark 생성자

3.3 PerformanceMeasure 인터페이스

4. 처리

4.1 mark를 timestamp로 변환

4.2 name을 timestamp로 변환

5. 권장 mark 이름

6. 개인정보 보호와 보안

A. 감사의 말

B. 참고 문헌

B.1 규범 참고 문헌

B.2 정보 참고 문헌

3.1 `Performance` 인터페이스에 대한 확장

3.1.1 `mark()` 메서드

3.1.1.1 `PerformanceMarkOptions` 딕셔너리

3.1.2 `clearMarks()` 메서드

3.1.3 `measure()` 메서드

3.1.3.1 `PerformanceMeasureOptions` 딕셔너리

3.1.4 `clearMeasures()` 메서드

3.2 `PerformanceMark` 인터페이스

3.2.1 `PerformanceMark` 생성자

3.3 `PerformanceMeasure` 인터페이스

4.1 `mark`를 `timestamp`로 변환

4.2 `name`을 `timestamp`로 변환