Intent to Deprecate and Remove: Legacy callback-based RTCPeerConnection.getStats() API

[Henrik Boström]

This deprecation is not to be confused with the track stats deprecation, 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

hb...@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 which may still be a useful resource, but for latest information we refer to the modern API's spec and code search.

Summary

WebRTC is a set of JavaScript APIs (spec) 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.

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.

According to chromestatus.com stats,

- 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.

[Yoav Weiss]

Hey Henrik!

I think the general outline of the plan makes sense, but the timelines seem too aggressive. As we've recently seen in the track stats removal, there can be a time difference between the point a developer puts in the work to opt-in for a deprecation trial and the point in which this work reaches users.

I think it would make sense to:

* Add a deprecation warning in M113 and enable a Deprecation Trial. Set a tentative removal milestone for M119.

* Start throwing an exception up to Beta in M114 to try and get people's attention

* Broadly communicate this change is coming in multiple channels. DevRel folks may be able to help there. +Paul Kinlan and +Andre Bandarra for thoughts.

* In parallel to the above, turn the usecounters into UKM, and try to see where most usage lies. (and try to understand if it's coming from libraries with longer deployment lifecycles)

* Flip the switch (and be ready to revert) in M119

I know this is a bit longer and more work than the plan you outlined, but given the few fire drills we had recently, it seems better to err on the cautious side.

Also, do you know if more removals are planned on your side? It seems like it'd be better to "bundle" them so that library authors only have to "respin" their deployment once, rather than every few milestones.

 

--
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+...@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.

[Philipp Hancke]

hey Yoav,

Am Fr., 17. Feb. 2023 um 08:52 Uhr schrieb Yoav Weiss <yoav...@chromium.org>:

Hey Henrik!

I think the general outline of the plan makes sense, but the timelines seem too aggressive. As we've recently seen in the track stats removal, there can be a time difference between the point a developer puts in the work to opt-in for a deprecation trial and the point in which this work reaches users.

Your view might be skewed by that incident which I would classify as minor and with relatively good communication upfront.

For scale, this is what I call a meltdown ;-)

WebRTC is a complex (monolithical) API that still is not done after more than a decade.

Commits to libwebrtc (which rolls into Chrome as a dependency) are still around 200 per month (peak was around 600 in 2017).

The challenge is that a lot of the subtle changes in behavior are nontrivial to detect, see e.g. this one.

Some breakage gets caught early enough in the process by vendor CI systems (e.g. here and that isn't even related directly to WebRTC) that it doesn't make it to stable.

Compared to dealing with those kind of issues (which in the best case come with a 4-8 week window) a planned deprecation is easy ;-)

I think it would make sense to:

* Add a deprecation warning in M113 and enable a Deprecation Trial. Set a tentative removal milestone for M119.

* Start throwing an exception up to Beta in M114 to try and get people's attention

* Broadly communicate this change is coming in multiple channels. DevRel folks may be able to help there. +Paul Kinlan and +Andre Bandarra for thoughts.

* In parallel to the above, turn the usecounters into UKM, and try to see where most usage lies. (and try to understand if it's coming from libraries with longer deployment lifecycles)

* Flip the switch (and be ready to revert) in M119

I know this is a bit longer and more work than the plan you outlined, but given the few fire drills we had recently, it seems better to err on the cautious side.

Also, do you know if more removals are planned on your side? It seems like it'd be better to "bundle" them so that library authors only have to "respin" their deployment once, rather than every few milestones.

There are a few that might make sense to remove together:

• The legacy callback based variants of createOffer, setLocalDescription et al, graph here.
  The high setLocalDescription usage here is due to "WebRTC leaks my ip address" trackers (maybe breaking them makes them reevaluate whether after the mdns changes they still get useful data?)
  setRemoteDescription and getUserMedia give a much better relative baseline of actual usage.
• addStream which has been replaced by addTrack, graph here.
  
• RTCIceServer.url, see the tracking bug and graph here.
  Again hard to interpret due to "WebRTC leaks my ip address" (in this case the public one). Given that Safari throws and the change needed is to replace "url" with "urls" this still seems safe for actual usage.
• the nonstandard "negotiate" rtcpMuxPolicy, see the 2017 I2D and tracking bug. The good news is that the then-new version of Asterisk that no longer needed this has been EOL'd a while ago.
• The usage looks pretty low but even if the new metrics coming to M111 put it at 0.1% of relative WebRTC usage I'm concerned that this might represent callcenter usage where the WebCompat argument "does not work in Safari" does not apply because the callcenter agents use Chromebooks.
  ("Callcenters" are even more conservative than "enterprise usage" here, with breakages costing a lot of money)

None of those require changes which are as technically involved as the "plan-b deprecation".

For the first two https://github.com/fippo/webrtc-codemods even does the job automatically.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAL5BFfVSMZDhsem91YtBc0R56M37SU4wi7s2bQcux4jjLkf9CA%40mail.gmail.com.

[Henrik Boström]

OK, so deprecation warning in M113, throwing in Beta in M114 and throwing in Stable on M119. We can do that.

Under this less aggressive timeline, for how many more milestones would the Deprecation Trial span?

I do not have any more deprecations planned on my end and I think this is "standalone" enough (stats being rather specific) that in my opinion it should not be bundled together with anything else.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Yoav Weiss]

On Mon, Feb 20, 2023 at 12:52 PM Henrik Boström <hb...@chromium.org> wrote:

OK, so deprecation warning in M113, throwing in Beta in M114 and throwing in Stable on M119. We can do that.

Awesome!

 

Under this less aggressive timeline, for how many more milestones would the Deprecation Trial span?

How much would be needed for people to schedule the work to make the switch? 

 

I do not have any more deprecations planned on my end and I think this is "standalone" enough (stats being rather specific) that in my opinion it should not be bundled together with anything else.

OK, cool!

 

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

[Henrik Boström]

On Thursday, February 23, 2023 at 11:03:44 AM UTC+1 Yoav Weiss wrote:

On Mon, Feb 20, 2023 at 12:52 PM Henrik Boström <hb...@chromium.org> wrote:

OK, so deprecation warning in M113, throwing in Beta in M114 and throwing in Stable on M119. We can do that.

Awesome!

 

Under this less aggressive timeline, for how many more milestones would the Deprecation Trial span?

How much would be needed for people to schedule the work to make the switch? 

If they notice the deprecation warning they would have enough time to migrate before the Deprecation Trial is even needed. If they don't, how about 3 months extra?

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Yoav Weiss]

SGTM

[Henrik Boström]

In that case the proposal is:

- Add deprecation warning in M113 (Release: May 2, 2023) with the possibility to opt-in to the Deprecation Trial.

- Throw an exception if the trial is not used in Canary/Dev/Beta in M114.

- Throw an exception if the trial is not used in Stable in M119 (Release: October 31, 2023).

- Let M121 be the last version where the Trial is available (Release: January 9, 2024). In other words the first version where the trial and legacy getStats API is entirely removed is M122 (Release: February 6, 2024).

[Yoav Weiss]

LGTM1 for that plan

[Philip Jägenstedt]

I think the overall timeline looks great, the final removal is almost a year from now, after the 2023 holiday season.

However, I'd like to bikeshed "Throw an exception if the trial is not used in Stable in M119 (Release: October 31, 2023)". This is when the breakage will be apparent to most users/developers, anyone who isn't paying attention to deprecation warnings. Oct 31 doesn't give a whole lot of time to figure out how origin trials work and opt into that, so I would suggest M117, stable on Aug 30. That's as early as seems reasonable given summer vacations in the northern hemisphere.

WDYT Henrik, would that work just as well for you?

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAL5BFfXvoddJYizkHGzmavf6LLyqxY1VGLfZfW%3D%2BrmZBBHNq8Q%40mail.gmail.com.

[Henrik Boström]

Yes, I think throwing in M117, stable on Aug 30 would be even better.

[Yoav Weiss]

SGTM!

[Philip Jägenstedt]

LGTM2, even better!

[Mike Taylor]

LGTM3

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAARdPYfRn4nBRmfmvgJ8DFnmEZaCN_fGxqkEGsYK9z2ndyL1fQ%40mail.gmail.com.

[Mason Freed]

Chiming in briefly here - it appears (from my console messages) that BrowserStack is currently hitting this deprecation. BrowserStack sessions in M115 restart on ~5 second intervals with a console error pointing to this deprecation.  Might be worth reaching out to them to talk about mitigations.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAARdPYfRn4nBRmfmvgJ8DFnmEZaCN_fGxqkEGsYK9z2ndyL1fQ%40mail.gmail.com.

[Henrik Boström]

Thanks Mason, we're reaching out

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CAARdPYfRn4nBRmfmvgJ8DFnmEZaCN_fGxqkEGsYK9z2ndyL1fQ%40mail.gmail.com.