WebRTC 診断ログ API

1. はじめに

WebRTC 診断ログ API は、Web アプリケーションが、ユーザーエージェントによって実行される WebRTC 関連の処理に関する内部診断ログの収集を開始、終了、および取り消すための プログラムインターフェイスを提供します。 これらの診断ログがアプリケーションに公開されることはありません。代わりに、 ユーザーエージェントによってローカルに保存され、ユーザーの管理下に置かれます。 ユーザーエージェントは、ユーザーエージェントが決定したエンドポイントに 診断ログをアップロードすることもできます。 診断ログの収集、保存、およびアップロードには、ユーザーによる明示的な 許可が必要であり、アプリケーションはこれらの処理が成功したかどうかを認識しません。 診断ログの内容も実装の詳細です。 この API が対応することを意図しているユースケースは次のとおりです。

• アプリケーションがログの収集を要求し、そのログがローカルに保存されます。 これらのログは、開発者がアプリケーションのバグを診断するために使用できます。 アプリケーションのユーザーは、バグの修正またはその他の方法でアプリケーションを 改善するために、これらのログをアプリケーション開発者に提供できます。 組織は、バグの診断または改善を行うために、ユーザーからこれらのログを 収集できます。

• アプリケーションは、ログをユーザーエージェントのベンダーと共有するよう要求できます。 これは、アプリケーション開発者がユーザーエージェントのバグを疑い、 ユーザーエージェントの開発者によるバグ修正を支援するためにログを提供したい場合に 役立ちます。このユースケースに対応するため、API は、アップロードされた診断ログを 識別するためにバグ報告へ含めることができる UUID を返します。この仕組みにより、 ユーザーは診断ログをユーザーエージェントのベンダーに公開することを許可できますが、 診断ログをアプリケーションに公開することはできません。

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

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

診断ログの収集、保存、およびアップロードには、ユーザーによる明示的な 許可が必要です。この許可の具体的な仕組みは実装の詳細です。許可を実装するための 選択肢には、専用 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. 内部スロット

関連する大域オブジェクトが、 [[RTCDiagnosticLoggingSessionId]] 内部スロットを持ち、初期値が null であるものとします。

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 によって識別されるログ記録セッションに 関連付けられたデータを、ユーザーエージェントのベンダーと共有してはなりません。