Introducing UserInteractions

Mike Conley mconley at
Fri Oct 23 20:26:27 UTC 2020

Hey firefox-dev,

TL;DR: New UserInteraction thing that front-end can use to help make hang
reports easier to reason about! Documentation here:

You may or may not know this, but we have this component that runs in
Nightly called BackgroundHangReporter, or BHR. It's job is to notice when
monitored threads (like the main thread) hang, and then to collect
interesting information about the hang (like its length, a stack from the
hang, etc), and then submit them to Telemetry.

BHR has been enabled for quite a few years, but part of the problem with
the BHR data that we get is that we have a hard time getting a sense of
what the user might have been doing when the hang occurred. Knowing that
might help us diagnose the hang, and could certainly help us rank and
prioritize hangs (since a hang that occurs when the user is typing in the
URL bar is probably more important to examine than a hang that occurs when
the user has another application in the foreground).

BHR has always had a mechanism for annotating hangs with richer
information, but that mechanism has never been exposed to privileged

Until now!

Introducing UserInteraction: a privileged global that one uses to hint to
BHR what the user is doing in the event that a hang occurs.

If you're familiar with TelemetryStopwatch, the API is somewhat similar
with regards to starting, canceling, checking running state, and finishing.
Here's some documentation showing how you can use it:

and here's a patch where I landed the first UserInteraction, for tab

My hope is that we can use UserInteraction's to wrap our most critical
main-thread user interaction points in our code base, and then surface the
most important hangs in our BHR data. As a bonus, this also gives you
profiler markers for your UserInteraction as a byproduct, and who doesn't
want those?


Q: Does this work in content processes or off main thread?

A: No. This will only work for the main thread in the parent process for
now. If it turns out that we want to add this kind of stuff for content
processes or different threads, I guess we can entertain the possibility -
but this was very much designed with user interactions with the browser UI
in mind.

Q: Can I just add UserInteractions willy-nilly, no holds barred?

A: UserInteractions are essentially a new form of data collection, so
adding them requires adding an entry to UserInteractions.yaml and getting
data-review+ from a Data Steward.

Q: Where can I see the BHR data that's being collected?

A: Two part answer:

If you go to about:telemetry, it'll be in your Archived Ping Data within a
"bhr" ping. That'll show you what you're submitting locally.

But if you're asking "where's the aggregated set of data that we can do
analysis on", ah, here's the rub. There have been several heroic attempts
to make better use of this data and to make it more accessible. See and for
example. We don't think we've really nailed the post-processing and
visualization necessary to make this information broadly useful yet. We're
hoping that UserInteractions can help us inch towards actionable data.
Getting a full blown BHR dashboard would be lovely, and it's something
we're actively investigating the practicalities of. (We're also chatting
with the crash pings team, as they're solving somewhat similar problems.)

Q: What's the difference between TelemetryStopwatch and UserInteractions?

While the APIs look similar, the end results are very different.

TelemetryStopwatch will ultimately add a value to a Telemetry Histogram.

UserInteractions will annotate hangs sent via BHR if a hang occurs while
the UserInteraction is running. (It will also add a profiler marker as a

Q: I have questions, concerns or opinions that aren't articulated here in
this FAQ. What do I do about that?

A: You can either respond to this thread here on firefox-dev, you can email
me personally, or you can drop a note in #fx-perf on Matrix.

All the best,

-Mike (:mconley)
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <>

More information about the firefox-dev mailing list