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 DOMString startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  static undefined stopDiagnosticLogging();
  static undefined cancelDiagnosticLogging();
};

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. If the [[RTCDiagnosticLoggingSessionId]] internal slot is not null, throw an "InvalidStateError" DOMException.

5. Let sesssionId be a randomly generated UUID [rfc4122]. To avoid fingerprinting, implementations SHOULD use the form in section 4.4 of RFC 4122 when generating UUIDs.

6. Set [[RTCDiagnosticLoggingSessionId]] to sessionId.

7. In parallel, start a logging session of internal WebRTC activity, using metadata for context. Identify the logging session with sessionId.

8. Return sessionId.

Once a logging session starts, the user agent MAY log any WebRTC-related activity. The logging session is identified with sessionId, which can be used to reference logs (e.g., in bug reports).

3.3.2. stopDiagnosticLogging()

The stopDiagnosticLogging() method ends an ongoing diagnostic logging session.

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

1. If the [[RTCDiagnosticLoggingSessionId]] internal slot is null, throw an "InvalidStateError" DOMException.

2. Let sessionId be [[RTCDiagnosticLoggingSessionId]].

3. Set [[RTCDiagnosticLoggingSessionId]] to null.

4. In parallel, stop the logging session identified with [[RTCDiagnosticLoggingSessionId]].

The user agent MUST NOT log any WebRTC-related activity once the logging session has stopped.

3.3.3. discardDiagnosticLogging()

The discardDiagnosticLogging() method cancels 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. If the [[RTCDiagnosticLoggingSessionId]] internal slot is null, throw an "InvalidStateError" DOMException.

2. Let sessionId be [[RTCDiagnosticLoggingSessionId]].

3. Set [[RTCDiagnosticLoggingSessionId]] to null.

4. In parallel, cancel the logging session identified with [[RTCDiagnosticLoggingSessionId]].

Once the logging session is canceled, the user agent MUST NOT log any WebRTC-related activity and the user agent MUST have removed any logged data associated with the canceled logging session.