diff --git a/index.html b/index.html index 55d1d83..3078fd3 100644 --- a/index.html +++ b/index.html @@ -1802,6 +1802,310 @@

+
+

Diagnostic logging

+ The WebRTC Diagnostic Logging API provides a programmatic interface for web + applications to start, finish, and cancel the collection of internal diagnostic + logs for WebRTC-related operations performed by the user agent. + These diagnostic logs are never exposed to the application. Instead they are + stored locally by the user agent and are under the control of the user. + The user agent can also upload the diagnostic logs to an endpoint decided by + the user agent. + The collection, storage and upload of diagnostic logs requires explicit + authorization by user and the application never knows if these operations + succeed. The contents of the diagnostic logs are also an implementation + detail. + The use cases intended to be supported by this API are the following: + +
+

Security and Privacy

+ These diagnostic logs collect information about internal operations performed + by the user agent to implement WebRTC-related features. These diagnostic logs + may contain information not exposed to the Web application and therefore, the + API cannot expose these logs to the Web application in any way. The logs may, + subject to user authorization, be shared (via out-of-band uploads, for example) + with the user-agent vendor so that they can be used to assist in fixing + user-agent bugs or providing other improvements to the user agent. + + The collection, storage and upload of diagnostic logs requires explicit + authorization by the user. The specific mechanism for this authorization is + [=implementation-defined=]. Some options to implement authorization include, but are + not limited to, dedicated UI, settings, enterprise policies, prompts, or + combination thereof. Authorization may be limited to specific origins. The + status of these authorizations is never exposed to the application. Therefore, + the APIs provide no guarantees of success. +
+
+

Extensions to the RTCPeerConnection Interface

+ The API is exposed as a set of static methods on the {{RTCPeerConnection}} + interface. + 
+          [
+            Exposed=Window
+          ] partial interface RTCPeerConnection {
+            static Promise<DOMString> startDiagnosticLogging(optional RTCStartDiagnosticLoggingOptions options = {});
+            static Promise<undefined> finishDiagnosticLogging(optional RTCFinishDiagnosticLoggingOptions options = {});
+            static Promise<undefined> cancelDiagnosticLogging();
+          };
+
+          dictionary RTCDiagnosticLoggingOptions {
+            record<DOMString, DOMString> metadata;
+          };
+
+          dictionary RTCStartDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
+            boolean allowUpload = false;
+          };
+
+          dictionary RTCFinishDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
+          };
+
+
+
+

Internal slots

+ Let the the [=relevant global object=] have an + [[\RTCDiagnosticLoggingSessionId]] + internal slot, initialized to null. +
+
+

Methods

+
+
+ startDiagnosticLogging +
+
+

The {{startDiagnosticLogging}} method attempts to start a diagnostic + logging session.

+

When this method is invoked, the [= user agent =] MUST run the following steps:

+
    +
  1. +

    Let |options| be the first argument of this method.

    +
    2. +
  2. +

    Let |allowUpload| be |options|'s + {{RTCStartDiagnosticLoggingOptions/allowUpload}} member.

    +
    3. +
  3. +

    Let |metadata| be |options|'s + {{RTCDiagnosticLoggingOptions/metadata}} member.

    +
    4. +
  4. +

    If the size of |metadata| exceeds 5 entries, or if any key or + value in |metadata| exceeds 100 characters, return a promise + [=rejected=] with a {{TypeError}}.

    +
    5. +
  5. +

    Let |p| be a new promise.

    +
    6. +
  6. +

    [=In parallel=], perform the following steps:

    +
      +
    1. +

      Let |uuid| be a randomly generated UUID [[rfc4122]], which + is 36 characters long in its canonical form. To avoid + fingerprinting, implementations SHOULD use the forms in + section 4.4 or 4.5 of RFC 4122 when generating UUIDs.

      +
      2. +
    2. +

      Let |doc| be the [=relevant global object=]'s associated [=document=].

      +
      3. +
    3. +

      If |doc|'s [=browsing context=] is not a [=top-level browsing context=], + [=resolve=] |p| with |uuid| and abort these steps.

      +
      4. +
    4. +

      If the {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}} internal slot + is not null, [=resolve=] |p| with |uuid| and abort these steps.

      +
      5. +
    5. +

      Store |uuid| in the {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}} + internal slot.

      +
      6. +
    6. +

      [=Resolve=] |p| with |uuid|.

      +
      7. +
    7. +

      Start a logging session of internal WebRTC activity identified with |uuid|

      +
      8. +
    +
    7. +
  7. +

    Return |p|.

    +
    8. +
+

+ Once a logging session starts, any WebRTC-related activity generated + by |doc| or its descendant documents that are of the [=same origin=] + as |doc| MAY be logged by the user agent after |p| resolves. + The log MAY include |metadata| or information derived from it. + If |allowUpload| is true, the logged data may be shared with the + user agent vendor via an [=implementation-defined=] mechanism, as long as the user + has authorized it and the logging session has not been cancelled with the + {{cancelDiagnosticLogging}} method. The logging session is identified with + |uuid|, which means that all logged data can be internally referenced using + |uuid|. +

+
+
+ finishDiagnosticLogging +
+
+

The {{finishDiagnosticLogging}} method ends an ongoing diagnostic logging session.

+

When this method is invoked, the [= user agent =] MUST run the following steps:

+
    +
  1. +

    Let |options| be the first argument of this method.

    +
    2. +
  2. +

    Let |metadata| be |options|'s {{RTCDiagnosticLoggingOptions/metadata}} member.

    +
    3. +
  3. +

    If the size of |metadata| exceeds 5 entries, or if any key or value + in |metadata| exceeds 100 characters, return a promise [=rejected=] + with a {{TypeError}}.

    +
    4. +
  4. +

    Let |p| be a new promise.

    +
    5. +
  5. +

    [=In parallel=], perform the following steps:

    +
      +
    1. +

      If the {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}} + internal slot is null, [=resolve=] |p| with + undefined and abort these steps.

      +
      2. +
    2. +

      Stop the logging session identified with + {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}}.

      +
      3. +
    3. +

      Set {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}} + to null.

      +
      4. +
    4. +

      [=Resolve=] |p| with undefined.

      +
      5. +
    +
    6. +
  6. +

    Return |p|.

    +
    7. +
+

+ The user agent MUST not log any WebRTC-related activity generated by |doc| or + its descendant documents after the |p| resolves. The log MAY + include |metadata| or information derived from it. The user agent MAY share the + logged data out of band with the user-agent vendor using an + [=implementation-defined=] mechanism, as long as the user has authorized it and the + logging session was initialized with + {{RTCStartDiagnosticLoggingOptions/allowUpload}} set to true. +

+
+
+ cancelDiagnosticLogging +
+
+

The {{cancelDiagnosticLogging}} method cancels an ongoing diagnostic logging session.

+

When this method is invoked, the [= user agent =] MUST run the following steps:

+
    +
  1. +

    Let |p| be a new promise.

    +
    2. +
  2. +

    [=In parallel=], perform the following steps:

    +
      +
    1. +

      Let |uuid| be the value of the {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}}.

      +
      2. +
    2. +

      Cancel the logging session identified with + {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}}.

      +
      3. +
    3. +

      Set {{RTCPeerConnection/[[RTCDiagnosticLoggingSessionId]]}} + to null.

      +
      4. +
    4. +

      [=Resolve=] |p| with undefined.

      +
      5. +
    +
    3. +
  3. +

    Return |p|.

    +
    4. +
+

+ After |p| resolves: +

    +
  • + The user agent MUST not log any WebRTC-related activity + generated by |doc| or its descendant documents. +
    • +
  • + The user agent MUST remove any logged data associated with + the session identified with |uuid|. +
    • +
  • + The user agent MUST not share with the user-agent vendor any + data associated with the the logging session identified with + |uuid|. +
    • +
+

+
+
+
+
+

Dictionary {{RTCDiagnosticLoggingOptions}} members

+
+
+ metadata of type [=record=]<{{DOMString}}, {{DOMString}}>, + defaulting to []. +
+
+

+ A [=record=] containing key-value pairs that the application can + use to provide context that can be stored in the diagnostic logs. +

+
+
+
+
+

Dictionary {{RTCStartDiagnosticLoggingOptions}} members

+
+
+ allowUpload of type [=boolean=], + defaulting to false. +
+
+

+ If true, the [=user agent=] MAY share the logs from + the logging session with the [=user agent=] vendor. + If false, the [=user agent=] MUST NOT share the logs + from the logging session with the [=user agent=] vendor. +

+
+
+
+

Security Considerations