WebRTC 診断ログ API

1. はじめに

WebRTC Diagnostic Logging API は、Web アプリケーションが、ユーザーエージェントによって実行される WebRTC 関連操作の内部診断 ログの収集を開始、終了、および破棄するためのプログラムインターフェイスを提供する。 これらの診断ログがアプリケーションに公開されることはない。代わりに、それらは ユーザーが管理する場所に保存され、ユーザー エージェントのベンダーと共有される場合がある。 診断ログの収集および保存にはユーザーによる明示的な 承認が必要であり、アプリケーションは診断ログ操作が 成功したか失敗したかを知ることはない。診断ログの内容も 実装の詳細である。 この API がサポートすることを意図しているユースケースは次のとおりである。

• アプリケーションがログの収集を要求する。これらのログは、 開発者がアプリケーション内のバグを診断するために使用できる。 アプリケーションのユーザーは、バグの修正やその他の方法でアプリケーションを改善する 助けとなるよう、これらのログをアプリケーション開発者に提供できる。組織は、 バグを診断したり、内部 WebRTC 配備を 改善したりするために、ユーザーからこれらのログを収集できる。

• ユーザーは、ログがユーザーエージェントのベンダーと共有されるよう設定できる。これは、 アプリケーション開発者がユーザーエージェントにバグがあると疑い、 ユーザーエージェントの開発者によるバグ修正を支援するためにログを提供したい場合に 有用である。このユースケースをサポートするため、API は 診断ログセッションを識別するために使用できる UUID（例えば、バグ報告内で）を返す。この 仕組みによって診断ログがアプリケーションに公開されることはない。

2. セキュリティとプライバシー

これらの診断ログは、WebRTC 関連機能を実装するために ユーザーエージェントによって実行される内部操作に関する情報を収集する。これらの診断ログには、 Web アプリケーションに公開されない情報が含まれる可能性があり、そのため API はいかなる方法でもこれらのログを Web アプリケーションに公開してはならない。ログは、 ユーザーの承認を条件として、（例えば帯域外アップロードを介して） ユーザーエージェントのベンダーと共有され、ユーザーエージェントのバグ修正や ユーザーエージェントに対するその他の改善の支援に使用される場合がある。

診断ログの収集、保存、およびアップロードにはユーザーによる明示的な 承認が必要である。この承認の具体的な仕組みは 実装定義である。承認を実装する選択肢には、 専用 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. sesssionId をランダムに生成された 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 関連のアクティビティを一切記録してはならず、ユーザーエージェント は、 キャンセルされたログ記録セッションに関連する記録済みデータを すべて削除済みでなければならない。