WebRTC Diagnostic Logging API

1. Introduction

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:

• An application requests the collection of logs, which are stored locally. These logs can be used by a developer to help diagnose bugs in the application. A user of the application can provide these logs to an application developer in order to help fix bugs or otherwise improve the application. An organization can collect these logs from its users to diagnose bugs or make improvements.

• An application may request that the logs be shared with the user agent vendor. This is useful in case the application developer suspects a bug in the user agent and it wants to provide the logs to help the user agent developer fix the bug. To support this use case, the API returns a UUID that can be included in a bug report to identify an uploaded diagnostic log. This mechanism allows a user to authorize exposing the diagnostic log to the user agent vendor, but it does not allow exposing the diagnostic log to the application.

2. 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 an implementation detail. 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.

3. Extensions to the RTCPeerConnection Interface

The API is exposed as a set of static methods on the RTCPeerConnection interface.

[
  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. Dictionaries

The RTCStartDiagnosticLoggingOptions and RTCFinishDiagnosticLoggingOptions provide configuration for the logging session.

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

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

dictionary RTCFinishDiagnosticLoggingOptions : RTCDiagnosticLoggingOptions {
};

3.2. Internal slots

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

3.3. Methods

3.3.1. startDiagnosticLogging(options)

The startDiagnosticLogging(options) method must run these steps:

1. Let allowUpload be options’s allowUpload member.

2. Let metadata be options’s metadata member.

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. Let p be a new promise.

5. In parallel, perform the following steps:

   1. Let uuid be a universally unique ID.

   2. Let doc be the relevant global object’s associated document.

   3. If doc’s browsing context is not a top-level browsing context, resolve p with uuid and abort these steps.

   4. If the [[RTCDiagnosticLoggingSessionId]] internal slot is not null, resolve p with uuid and abort these steps.

   5. Store uuid in the [[DiagnosticLoggingSessionId]] internal slot.

   6. Resolve p with uuid.

   7. Start a logging session of internal WebRTC activity identified with uuid

6. Return p.

Once a logging session starts, any WebRTC-related activity generated by doc or its descendant documents 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.

3.3.2. finishDiagnosticLogging(options)

The cancelDiagnosticLogging(options) method must run these steps:

1. Let metadata be options’s metadata member.

2. 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.

3. Let p be a new promise.

4. In parallel, perform the following steps:

   1. If the [[RTCDiagnosticLoggingSessionId]] internal slot is null, resolve p with undefined and abort these steps.

   2. Stop the logging session identified with [[RTCDiagnosticLoggingSessionId]].

   3. Set [[RTCDiagnosticLoggingSessionId]] to null.

   4. Resolve p with undefined.

5. Return p.

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 allowUpload set to true.

3.3.3. cancelDiagnosticLogging()

The cancelDiagnosticLogging() method must run these steps:

1. Let p be a new promise.

2. In parallel, perform the following steps:

   1. Let uuid be the value of the [[RTCDiagnosticLoggingSessionId]] internal slot.

   2. Cancel the logging session identified with [[RTCDiagnosticLoggingSessionId]].

   3. Set [[RTCDiagnosticLoggingSessionId]] to null.

   4. Resolve p with undefined.

3. Return p.

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.