WebRTC Diagnostic Logging API

at a glance

Syntax

The API hangs off Navigator as a single read-only rtc attribute returning an RTC instance with three asynchronous session methods. IDL from the WICG draft:

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

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

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

startDiagnosticLogging(options)

Begins a logging session. The user agent starts recording internal WebRTC logs for the calling browsing context and its descendants. Resolves with a unique session ID (a UUID) — the only piece of diagnostic information the application ever receives.

finishDiagnosticLogging()

Ends the session and finalizes the log file. The promise resolves when the session is successfully closed, and the user agent must not log WebRTC activity for the session afterwards. If the session was started with allowUpload: true, the user agent may upload the finalized log to a user-agent-defined endpoint — again, only with user authorization.

cancelDiagnosticLogging()

Stops the session and discards everything collected. The promise resolves when the session is terminated; the user agent must not log afterwards, and because the data is discarded it cannot be uploaded. (The explainer's example code calls this cancelLogging(), but the specification's IDL — the authoritative surface — names it cancelDiagnosticLogging().)

What the app can and cannot see

The design deliberately keeps diagnostic content away from the application. The explainer states as an explicit non-goal that the API exposes nothing to the app beyond the session ID — the logs may contain internal information about user activity. The finished log is stored as a local file that the user can access, and the optional upload path shares it with the user agent (the browser vendor) — never with the site. The format of the log and the upload mechanism are intentionally unspecified; the only hard requirement is explicit user authorization. A site can attach small pieces of metadata (for example an app identifier) so a shared log can be matched to a bug report filed with the browser vendor.

Examples

// Before starting a call — begin a session (optionally allow upload + metadata)
const sessionId = await navigator.rtc.startDiagnosticLogging({
  allowUpload: true,
  metadata: { app: "my-call-app" },   // <= 5 pairs, <= 100 chars each
});
// The app stores the session ID — it is the ONLY data it ever gets back.

// When the call ends normally — finalize the log locally
await navigator.rtc.finishDiagnosticLogging();

// When the captured session is not useful — discard it entirely
await navigator.rtc.cancelDiagnosticLogging();

Browser compatibility

There is no browser-compat-data (BCD) entry for this API yet, so the table below is an interim view built from ChromeStatus ship data and public signals — not from BCD.

Beyond vendor signals, the explainer records stakeholder positions: Google (implementer) positive, and ByteDance positive (as a WebRTC application stakeholder, not a browser vendor).

Specifications

See also

• WICG — WebRTC Diagnostic Logging explainer
• W3C webrtc-extensions proposal — diagnostic logging
• Chrome origin trials — registration
• Chrome Platform Showcase — WebRTC Diagnostic Logging API (also: capability & policy probe, bug-report companion)