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 application may request that the logs be uploaded by the user agent. 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 developer, 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 user agent may upload these logs 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 or prompts. 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.

Access to the API is limited to secure contexts.

3. Extensions to the Navigator Interface

The API is exposed as an attribute on the Navigator interface.

[Exposed=Window]
partial interface Navigator {
  [SameObject] readonly attribute RTC rtc;
};

4. Interface RTC

The RTC interface manages the lifecycle of a diagnostic logging session.

[
  Exposed=Window,
  SecureContext
] interface RTC {
  Promise<DOMString> startDiagnosticLogging(optional RTCDiagnosticLoggingOptions options = {});
  Promise<undefined> finishDiagnosticLogging();
  Promise<undefined> cancelDiagnosticLogging();
};

4.1. Dictionary RTCDiagnosticLoggingOptions

The RTCDiagnosticLoggingOptions dictionary provides configuration for the logging session.

dictionary RTCDiagnosticLoggingOptions {
  boolean allowUpload = false;
  record<DOMString, DOMString> metadata;
};

5. Methods

5.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 exceeds 100 characters, return a Promise rejected with a TypeError.

4. Request the user agent to begin recording internal WebRTC logs.

5. Return a Promise that resolves with a unique session ID (UUID).

Any WebRTC-related activity generated by the browsing context and its descendant browsing contexts MAY be logged by the user agent after the promise resolves. The log file MAY include metadata. If allowUpload is true, the collected data may be shared with the user agent via an internal upload mechanism, as long as the user has authorized it and the logging session is not cancelled with the cancelDiagnosticLogging method.

5.2. finishDiagnosticLogging()

The finishDiagnosticLogging() method requests the user agent to finish recording and finalize the log file. It returns a Promise that resolves when the session is successfully closed.

The user agent MUST not log WebRTC-related activity after the Promise is resolved. The user agent MAY upload the log file to a user-agent defined if the logging session was initialized with allowUpload set to true, subject to user authorization.

5.3. cancelDiagnosticLogging()

The cancelDiagnosticLogging() method must request the user agent to stop recording and discard any data collected during the session. It returns a Promise that resolves when the session is terminated.

The user agent MUST not log WebRTC-related activity after the Promise is resolved. Since the logged data MUST be discarded, it is also not possible to upload it.