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 DOMString startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static undefined stopDiagnosticLogging();
  static undefined cancelDiagnosticLogging();
};

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보다 크거나, 임의의 항목 key → value에 대해 metadata 내 해당 항목의 길이가 100보다 크면, 다음 예외로 거부된 프로미스를 반환합니다: TypeError.

4. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이 아니면, 다음 예외를 던집니다: "InvalidStateError" DOMException.

5. sessionId를 무작위로 생성한 UUID [rfc4122]로 합니다. 핑거프린팅을 방지하기 위해, 구현체는 UUID를 생성할 때 RFC 4122의 4.4절에 제시된 형식을 사용하는 것이 좋습니다.

6. [[RTCDiagnosticLoggingSessionId]] 를 sessionId로 설정합니다.

7. 병렬로, 내부 WebRTC 활동의 로깅 세션을 시작하고, 문맥 정보로 metadata를 사용합니다. 로깅 세션은 sessionId로 식별합니다.

8. sessionId를 반환합니다.

로깅 세션이 시작되면, 사용자 에이전트는 모든 WebRTC 관련 활동을 기록해도 됩니다. 로깅 세션은 sessionId로 식별되며, 이 값은 로그를 참조하는 데 사용할 수 있습니다(예: 버그 보고서에서).

3.3.2. stopDiagnosticLogging()

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

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

1. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이면, 다음 예외를 던집니다: "InvalidStateError" DOMException.

2. sessionId를 [[RTCDiagnosticLoggingSessionId]]로 합니다.

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

4. 병렬로, 로깅 세션을 중지하며, 이 세션은 [[RTCDiagnosticLoggingSessionId]]로 식별됩니다.

로깅 세션이 중지되면 사용자 에이전트는 어떠한 WebRTC 관련 활동도 기록해서는 안 됩니다.

3.3.3. discardDiagnosticLogging()

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

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

1. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이면, 다음 예외를 던집니다: "InvalidStateError" DOMException.

2. sessionId를 [[RTCDiagnosticLoggingSessionId]]로 합니다.

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

4. 병렬로, 로깅 세션을 취소하며, 이 세션은 [[RTCDiagnosticLoggingSessionId]]로 식별됩니다.

로깅 세션이 취소되면, 사용자 에이전트는 어떠한 WebRTC 관련 활동도 기록해서는 안 되며, 사용자 에이전트는 취소된 로깅 세션과 관련하여 기록된 모든 데이터를 제거한 상태여야 합니다.