WebRTC 진단 로깅 API

1. 소개

WebRTC 진단 로깅 API는 웹 애플리케이션이 사용자 에이전트가 수행하는 WebRTC 관련 작업의 내부 진단 로그 수집을 시작하고, 완료하고, 폐기할 수 있는 프로그래밍 인터페이스를 제공합니다. 이러한 진단 로그는 애플리케이션에 절대 노출되지 않습니다. 대신 사용자가 제어하는 위치에 저장되며 사용자 에이전트 공급업체와 공유될 수 있습니다. 진단 로그의 수집 및 저장에는 사용자의 명시적인 승인이 필요하며 애플리케이션은 진단 로깅 작업의 성공 또는 실패 여부를 알 수 없습니다. 진단 로그의 내용 또한 구현 세부 사항입니다. 이 API에서 지원하려는 사용 사례는 다음과 같습니다.

• 애플리케이션이 로그 수집을 요청합니다. 개발자는 이 로그를 사용하여 애플리케이션의 버그를 진단하는 데 도움을 받을 수 있습니다. 애플리케이션 사용자는 버그 수정이나 그 밖의 애플리케이션 개선을 돕기 위해 이 로그를 애플리케이션 개발자에게 제공할 수 있습니다. 조직은 버그를 진단하거나 내부 WebRTC 배포를 개선하기 위해 사용자로부터 이러한 로그를 수집할 수 있습니다.

• 사용자는 로그가 사용자 에이전트 공급업체와 공유되도록 구성할 수 있습니다. 이는 애플리케이션 개발자가 사용자 에이전트의 버그를 의심하고 사용자 에이전트 개발자의 버그 수정을 돕기 위해 로그를 제공하려는 경우에 유용합니다. 이 사용 사례를 지원하기 위해 API는 진단 로깅 세션을 식별하는 데 사용할 수 있는 UUID를 반환합니다(예: 버그 보고서에서). 이 메커니즘을 통해 진단 로그가 애플리케이션에 노출되지는 않습니다.

2. 보안 및 개인정보 보호

이러한 진단 로그는 WebRTC 관련 기능을 구현하기 위해 사용자 에이전트가 수행한 내부 작업에 관한 정보를 수집합니다. 이러한 진단 로그에는 웹 애플리케이션에 노출되지 않는 정보가 포함될 수 있으므로 API는 어떤 방식으로도 이러한 로그를 웹 애플리케이션에 노출할 수 없습니다. 로그는 사용자의 승인을 전제로 사용자 에이전트 공급업체와 공유될 수 있으며(예: 대역 외 업로드를 통해), 이를 통해 사용자 에이전트의 버그 수정이나 그 밖의 사용자 에이전트 개선을 지원하는 데 사용할 수 있습니다.

진단 로그의 수집, 저장 및 업로드에는 사용자의 명시적인 승인이 필요합니다. 이 승인을 위한 구체적인 메커니즘은 구현에서 정의됩니다. 승인을 구현하는 방법에는 전용 UI, 구성 파일, 엔터프라이즈 정책, 프롬프트 또는 이들의 조합 등이 포함될 수 있으나 이에 한정되지는 않습니다. 승인은 특정 출처로 제한될 수 있습니다. 이러한 승인 상태는 애플리케이션에 절대 노출되지 않습니다. 따라서 API는 성공을 보장하지 않습니다.

3. RTCPeerConnection 인터페이스 확장

이 API는 RTCPeerConnection 인터페이스의 정적 메서드 집합으로 노출됩니다.

[
  Exposed=Window
] partial interface RTCPeerConnection {
  static Promise<DOMString> startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static Promise<undefined> finishDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static Promise<undefined> discardDiagnosticLogging();
};

3.1. 딕셔너리

RTCDiagnosticLoggingOptions는 로깅 세션을 위한 구성을 제공합니다.

dictionary RTCDiagnosticLoggingOptions {
  record<DOMString, DOMString> metadata;
};

3.2. 내부 슬롯

관련 전역 객체에 [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 있으며, 이 슬롯은 null로 초기화된다고 합니다.

3.3. 메서드

3.3.1. startDiagnosticLogging(options)

startDiagnosticLogging(options) 메서드는 진단 로깅 세션 시작을 시도합니다.

이 메서드가 호출되면 사용자 에이전트는 반드시 다음 단계를 실행해야 합니다.

1. options를 이 메서드의 첫 번째 인수라고 합니다.

2. metadata를 options의 metadata 멤버라고 합니다.

3. metadata의 크기가 5보다 크거나, metadata의 어떤 항목 key → value의 길이가 100보다 크다면, TypeError로 거부된 프로미스를 반환합니다.

4. p를 새 프로미스라고 합니다.

5. 병렬로 다음 단계를 수행합니다.

   1. uuid를 무작위로 생성된 UUID [rfc4122]라고 합니다. 핑거프린팅을 방지하기 위해 구현은 UUID를 생성할 때 RFC 4122의 4.4절에 있는 형식을 사용하는 것이 좋습니다.

   2. doc를 관련 전역 객체와 연결된 문서라고 합니다.

   3. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이 아니라면, DOMException 객체로 p를 거부합니다. 이 객체의 name 속성 값은 "InvalidStateError" 이며 이 단계들을 중단합니다.

   4. uuid를 [[RTCDiagnosticLoggingSessionId]] 내부 슬롯에 저장합니다.

   5. p를 uuid로 이행합니다.

   6. uuid로 식별되는 내부 WebRTC 활동의 로깅 세션을 시작합니다.

6. p를 반환합니다.

로깅 세션이 시작되면 p가 이행된 후 doc에서 생성된 모든 WebRTC 관련 활동을 사용자 에이전트가 로깅할 수 있습니다. 로그에는 metadata 또는 여기에서 파생된 정보가 포함될 수 있습니다. 로깅 세션은 uuid로 식별되며, 이는 로그를 참조하는 데 사용할 수 있습니다(예: 버그 보고서에서).

3.3.2. finishDiagnosticLogging(options)

finishDiagnosticLogging(options) 메서드는 진행 중인 진단 로깅 세션을 종료합니다.

이 메서드가 호출되면 사용자 에이전트는 반드시 다음 단계를 실행해야 합니다.

1. options를 이 메서드의 첫 번째 인수라고 합니다.

2. metadata를 options의 metadata 멤버라고 합니다.

3. metadata의 크기가 5보다 크거나, metadata의 어떤 항목 key → value의 길이가 100보다 크다면, TypeError로 거부된 프로미스를 반환합니다.

4. p를 새 프로미스라고 합니다.

5. 병렬로 다음 단계를 수행합니다.

   1. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이라면, DOMException 객체로 p를 거부합니다. 이 객체의 name 속성 값은 "InvalidStateError" 이며 이 단계들을 중단합니다.

   2. [[RTCDiagnosticLoggingSessionId]]로 식별되는 로깅 세션을 중지합니다.

   3. [[RTCDiagnosticLoggingSessionId]]를 null로 설정합니다.

   4. p를 undefined로 이행합니다.

6. p를 반환합니다.

p가 이행된 후 사용자 에이전트는 doc에서 생성된 어떠한 WebRTC 관련 활동도 반드시 로깅해서는 안 됩니다.

3.3.3. discardDiagnosticLogging()

discardDiagnosticLogging() 메서드는 진행 중인 진단 로깅 세션을 폐기하고 해당 세션과 연결된 모든 로깅 데이터를 삭제합니다.

이 메서드가 호출되면 사용자 에이전트는 반드시 다음 단계를 실행해야 합니다.

1. p를 새 프로미스라고 합니다.

2. 병렬로 다음 단계를 수행합니다.

   1. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이라면, DOMException 객체로 p를 거부합니다. 이 객체의 name 속성 값은 "InvalidStateError" 이며 이 단계들을 폐기합니다.

   2. uuid를 [[RTCDiagnosticLoggingSessionId]]의 값이라고 합니다.

   3. [[RTCDiagnosticLoggingSessionId]]로 식별되는 로깅 세션을 폐기합니다.

   4. [[RTCDiagnosticLoggingSessionId]]를 null로 설정합니다.

   5. p를 undefined로 이행합니다.

3. p를 반환합니다.

p가 이행된 후에는 다음과 같습니다.

• 사용자 에이전트는 doc에서 생성된 어떠한 WebRTC 관련 활동도 반드시 로깅해서는 안 됩니다.

• 사용자 에이전트는 uuid로 식별되는 세션과 연결된 모든 로깅 데이터를 반드시 제거해야 합니다.