WebRTC Diagnostic Logging API

1. Introduction

The WebRTC Diagnostic Logging API provides a programmatic interface for web applications to start, finish, and discard 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 in a location controlled by the user and may be shared with the user agent vendor. The collection and storage of diagnostic logs requires explicit authorization by user and the application never knows if diagnostic logging operations succeed or fail. 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. 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 to an internal WebRTC deployment.

• The user can configure logs to 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 used to identify a diagnostic logging session (e.g., in a bug report). This mechanism does not allow exposing the diagnostic logs 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 implementation-defined. Some options to implement authorization include, but are not limited to, dedicated UI, configuration files, enterprise policies, prompts, or a 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
] partial interface RTCPeerConnection {
  static Promise<DOMString> startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static Promise<undefined> finishDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static Promise<undefined> discardDiagnosticLogging();
};

3.1. Dictionaries

The RTCDiagnosticLoggingOptions provides configuration for the logging session.

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

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 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. Let metadata be options’s metadata member.

3. If metadata’s size is greater than 5, or if any entry key → value of metadata has a length greater than 100, 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 randomly generated UUID [rfc4122]. To avoid fingerprinting, implementations SHOULD use the form in section 4.4 of RFC 4122 when generating UUIDs.

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

   3. If the [[RTCDiagnosticLoggingSessionId]] internal slot is not null, reject p with a DOMException object whose name attribute has the value "InvalidStateError" and abort these steps.

   4. Store uuid in the [[RTCDiagnosticLoggingSessionId]] internal slot.

   5. Resolve p with uuid.

   6. 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 MAY be logged by the user agent after p resolves. The log MAY include metadata or information derived from it. The logging session is identified with uuid, which can be used to reference logs (e.g., in bug reports).

3.3.2. finishDiagnosticLogging(options)

The finishDiagnosticLogging(options) 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. Let metadata be options’s metadata member.

3. If metadata’s size is greater than 5, or if any entry key → value of metadata has a length greater than 100, return a promise rejected with a TypeError.

4. Let p be a new promise.

5. In parallel, perform the following steps:

   1. If the [[RTCDiagnosticLoggingSessionId]] internal slot is null, reject p with a DOMException object whose name attribute has the value "InvalidStateError" and abort these steps.

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

   3. Set [[RTCDiagnosticLoggingSessionId]] to null.

   4. Resolve p with undefined.

6. Return p.

The user agent MUST NOT log any WebRTC-related activity generated by doc after p resolves.

3.3.3. discardDiagnosticLogging()

The discardDiagnosticLogging() method discards an ongoing diagnostic logging session and deletes all logged data associated with the session.

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

1. Let p be a new promise.

2. In parallel, perform the following steps:

   1. If the [[RTCDiagnosticLoggingSessionId]] internal slot is null, reject p with a DOMException object whose name attribute has the value "InvalidStateError" and discard these steps.

   2. Let uuid be the value of the [[RTCDiagnosticLoggingSessionId]].

   3. Discard the logging session identified with [[RTCDiagnosticLoggingSessionId]].

   4. Set [[RTCDiagnosticLoggingSessionId]] to null.

   5. Resolve p with undefined.

3. Return p.

After p resolves:

• The user agent MUST NOT log any WebRTC-related activity generated by doc.

• The user agent MUST remove any logged data associated with the session identified with uuid.