WebRTC 진단 로깅 API

1. 소개

WebRTC 진단 로깅 API는 웹 애플리케이션이 사용자 에이전트가 수행하는 WebRTC 관련 작업의 내부 진단 로그 수집을 시작하고, 완료하고, 취소하기 위한 프로그래밍 인터페이스를 제공한다. 이러한 진단 로그는 애플리케이션에 절대 노출되지 않는다. 대신 사용자 에이전트가 로컬에 저장하며 사용자가 이를 제어한다. 사용자 에이전트는 사용자 에이전트가 결정한 엔드포인트로 진단 로그를 업로드할 수도 있다. 진단 로그의 수집, 저장 및 업로드에는 사용자의 명시적인 승인이 필요하며 애플리케이션은 이러한 작업의 성공 여부를 절대 알 수 없다. 진단 로그의 내용 또한 구현 세부 사항이다. 이 API가 지원하려는 사용 사례는 다음과 같다.

• 애플리케이션이 로컬에 저장되는 로그 수집을 요청한다. 개발자는 이러한 로그를 사용하여 애플리케이션의 버그를 진단할 수 있다. 애플리케이션 사용자는 버그 수정이나 기타 애플리케이션 개선을 돕기 위해 이러한 로그를 애플리케이션 개발자에게 제공할 수 있다. 조직은 버그를 진단하거나 개선하기 위해 사용자에게서 이러한 로그를 수집할 수 있다.

• 애플리케이션은 로그를 사용자 에이전트 공급자와 공유하도록 요청할 수 있다. 이는 애플리케이션 개발자가 사용자 에이전트의 버그를 의심하고 사용자 에이전트 개발자가 버그를 수정하는 데 도움이 되도록 로그를 제공하려는 경우에 유용하다. 이 사용 사례를 지원하기 위해 API는 업로드된 진단 로그를 식별하도록 버그 보고서에 포함할 수 있는 UUID를 반환한다. 이 메커니즘을 통해 사용자는 진단 로그를 사용자 에이전트 공급자에게 노출하도록 승인할 수 있지만 진단 로그를 애플리케이션에 노출할 수는 없다.

2. 보안 및 개인정보 보호

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

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

3. RTCPeerConnection 인터페이스의 확장

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

[
  Exposed=Window,
  SecureContext
] partial interface RTCPeerConnection {
  static Promise<DOMString> startDiagnosticLogging(optional RTCStartDiagnosticLoggingOptions options = {});
  static Promise<undefined> finishDiagnosticLogging(optional RTCFinishDiagnosticLoggingOptions options = {});
  static Promise<undefined> cancelDiagnosticLogging();
};

3.1. 딕셔너리

RTCStartDiagnosticLoggingOptions 및 RTCFinishDiagnosticLoggingOptions는 로깅 세션을 위한 구성을 제공한다.

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

dictionary RTCStartDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
  boolean allowUpload = false;
};

dictionary RTCFinishDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
};

3.2. 내부 슬롯

관련 전역 객체에 null로 초기화되는 [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 있다고 하자.

3.3. 메서드

3.3.1. startDiagnosticLogging(options)

startDiagnosticLogging(options) 메서드는 다음 단계를 실행해야 한다.

1. allowUpload을 options의 allowUpload 멤버로 설정한다.

2. metadata를 options의 metadata 멤버로 설정한다.

3. metadata의 크기가 5개 항목을 초과하거나 metadata의 키 또는 값이 100자를 초과하면 TypeError로 거부된 프로미스를 반환한다.

4. p를 새 프로미스로 설정한다.

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

   1. uuid를 범용 고유 ID로 설정한다.

   2. doc을 관련 전역 객체에 연결된 문서로 설정한다.

   3. doc의 브라우징 컨텍스트가 최상위 브라우징 컨텍스트가 아니면 p를 uuid로 이행하고 이 단계를 중단한다.

   4. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이 아니면 p를 uuid로 이행하고 이 단계를 중단한다.

   5. uuid를 [[DiagnosticLoggingSessionId]] 내부 슬롯에 저장한다.

   6. p를 uuid로 이행한다.

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

6. p를 반환한다.

로깅 세션이 시작되면 사용자 에이전트는 p가 이행된 후 doc 또는 그 하위 문서에서 생성된 모든 WebRTC 관련 활동을 기록할 수 있다. 로그에는 metadata 또는 여기에서 파생된 정보가 포함될 수 있다. allowUpload이 true이면 사용자가 이를 승인했고 로깅 세션이 cancelDiagnosticLogging 메서드로 취소되지 않은 한, 구현에서 정의한 메커니즘을 통해 기록된 데이터를 사용자 에이전트 공급자와 공유할 수 있다. 로깅 세션은 uuid로 식별되며, 이는 기록된 모든 데이터를 내부적으로 uuid를 사용하여 참조할 수 있음을 의미한다.

3.3.2. finishDiagnosticLogging(options)

cancelDiagnosticLogging(options) 메서드는 다음 단계를 실행해야 한다.

1. metadata를 options의 metadata 멤버로 설정한다.

2. metadata의 크기가 5개 항목을 초과하거나 metadata의 키 또는 값이 100자를 초과하면 TypeError로 거부된 프로미스를 반환한다.

3. p를 새 프로미스로 설정한다.

4. 병렬로 다음 단계를 수행한다.

   1. [[RTCDiagnosticLoggingSessionId]] 내부 슬롯이 null이면 p를 undefined로 이행하고 이 단계를 중단한다.

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

   3. [[RTCDiagnosticLoggingSessionId]]를 null로 설정한다.

   4. p를 undefined로 이행한다.

5. p를 반환한다.

사용자 에이전트는 p가 이행된 후 doc 또는 그 하위 문서에서 생성된 어떠한 WebRTC 관련 활동도 기록해서는 안 된다. 로그에는 metadata 또는 여기에서 파생된 정보가 포함될 수 있다. 사용자가 이를 승인했고 로깅 세션이 allowUpload을 true로 설정하여 초기화된 경우, 사용자 에이전트는 구현에서 정의한 메커니즘을 사용하여 기록된 데이터를 대역 외 방식으로 사용자 에이전트 공급자와 공유할 수 있다.

3.3.3. cancelDiagnosticLogging()

cancelDiagnosticLogging() 메서드는 다음 단계를 실행해야 한다.

1. p를 새 프로미스로 설정한다.

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

   1. uuid를 [[RTCDiagnosticLoggingSessionId]] 내부 슬롯의 값으로 설정한다.

   2. [[RTCDiagnosticLoggingSessionId]]로 식별되는 로깅 세션을 취소한다.

   3. [[RTCDiagnosticLoggingSessionId]]를 null로 설정한다.

   4. p를 undefined로 이행한다.

3. p를 반환한다.

p가 이행된 후에는 다음이 적용된다.

• 사용자 에이전트는 doc 또는 그 하위 문서에서 생성된 어떠한 WebRTC 관련 활동도 기록해서는 안 된다.

• 사용자 에이전트는 uuid로 식별되는 세션과 연결된 모든 기록 데이터를 제거해야 한다.

• 사용자 에이전트는 uuid로 식별되는 로깅 세션과 연결된 어떠한 데이터도 사용자 에이전트 공급자와 공유해서는 안 된다.