*This deprecation is not to be confused with the track stats deprecation <https://groups.google.com/a/chromium.org/g/blink-dev/c/NZVXsJQ7tV8>, which is deprecating a small subset of the modern API. This deprecation related to the removal of the legacy API, a different API with the same name.*
*Contact emails* h...@chromium.org, h...@chromium.org *Specification* The legacy getStats() API has no spec, no official documentation and no web platform tests. The modern (promise-based) version of getStats() does have a spec, but this is a different method returning different stats objects: https://w3c.github.io/webrtc-stats/ There are lots of similarities between the modern and legacy APIs, including several metrics that are the same, but the stats report structure is different and the legacy API contains several "goog"-prefixed metrics or metrics that behave differently from the modern API. In 2019, a document was created outlining the differences between the legacy and modern API <https://docs.google.com/document/d/1z-D4SngG36WPiMuRvWeTMN7mWQXrf1XKZwVl3Nf1BIE/edit?usp=sharing> which may still be a useful resource, but for latest information we refer to the modern API's spec <https://w3c.github.io/webrtc-stats/> and code search <https://source.chromium.org/chromium/chromium/src/+/main:third_party/webrtc/api/stats/rtcstats_objects.h> . *Summary* WebRTC is a set of JavaScript APIs (spec <https://w3c.github.io/webrtc-pc/>) enabling real-time communication, most notably realtime audio and video for Video Conferencing in the browser. getStats() is an API that allow apps to measure things like bitrate and media quality information about the session. The history is that spec and implementations evolved so quickly that the API was forked into two paths: the callback-based one that only exists in Chromium and has no spec and the promise-based one which has both a spec and pretty good cross-browser compatibility support <https://wpt.fyi/results/webrtc-stats/supported-stats.https.html?label=experimental&label=master&aligned> . In Chromium, the legacy API has been on feature freeze for several years and the goal was always to deprecate and remove it, but due to high usage this was not a possibility. This story is finally changing: usage graphs <https://webrtchacks.github.io/chromestatus/?buckets=1058,1476,1402&start=2022-01-01&window=7> . [image: Screenshot 2023-02-16 at 13.43.40.png] According to chromestatus.com stats <https://chromestatus.com/metrics/feature/popularity>, - RTCPeerConnectionGetStatsLegacyNonCompliant is 0.0183% and - RTCPeerConnectionGetStats is 0.2177% of page loads. In other words, legacy is 8% as popular as modern. According to UMA stats, - RTCPeerConnectionGetStatsLegacyNonCompliant is 0.000177% and - RTCPeerConnectionGetStats is 0.00114% of page loads. In other words, legacy is 15% as popular as modern. I don't know why UMAs and chromestatus shows different orders of magnitude when it comes to usage, but we're roughly talking about the legacy API being 1/10th as popular as the modern API. I think it is time to add a deprecation warning to the legacy API. *Risks* Usage is still high and migrating from the legacy API to the modern API may require a significant amount of work from developers. To mitigate this, we should have a long deprecation timeline and allow developers to opt-in to a Deprecation Trial to get more time. *Proposal* Add a deprecation warning in M113 and the possibility to opt-in to a deprecation trial. Add use counts for how many of the legacy API uses do and do not use the deprecation trial and track this over time. In M114, start throwing an exception in Canary/Beta if attempting to use the legacy API outside the trial *but do not throw* in Stable yet. Give apps more time to sign up to the trial. In M115, gently roll out the throwing of the exception to Stable, i.e. from this milestone onwards apps are required to use the deprecation trial if they want to continue to use the legacy getStats() API. M115 is Stable on June 27. Set the Deprecation Trial end date to M120 / December 5, 2023. This gives apps paying attention to the deprecation warning ~9 months to migrate and apps only paying attention to exceptions on stable ~6 months to migrate. -- You received this message because you are subscribed to the Google Groups "blink-dev" group. To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscr...@chromium.org. To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/8edb3ad3-c383-4c18-9595-81fb0732fa10n%40chromium.org.
