<div dir="ltr"><div>Hey firefox-dev,</div><div><br></div><div>TL;DR: New UserInteraction thing that front-end can use to help make hang reports easier to reason about! Documentation here:  <a href="https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/user-interactions.html">https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/user-interactions.html</a></div><div><br></div><div></div><div>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.</div><div><br></div><div>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).</div><div><br></div><div>BHR has always had a mechanism for annotating hangs with richer information, but that mechanism has never been exposed to privileged JavaScript.</div><div><br></div><div>Until now!</div><div><br></div><div>Introducing UserInteraction: a privileged global that one uses to hint to BHR what the user is doing in the event that a hang occurs.</div><div><br></div><div>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: <a href="https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/user-interactions.html">https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/collection/user-interactions.html</a></div><div><br></div><div>and here's a patch where I landed the first UserInteraction, for tab opening: <a href="https://hg.mozilla.org/mozilla-central/rev/9a6e825d7427">https://hg.mozilla.org/mozilla-central/rev/9a6e825d7427</a></div><div><br></div><div>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?</div><div><br></div><div>FAQ:</div><div><br></div><div>Q: Does this work in content processes or off main thread?</div><div><br></div><div>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.<br></div><div><br></div><div>Q: Can I just add UserInteractions willy-nilly, no holds barred?</div><div><br></div><div>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.</div><div><br></div><div>Q: Where can I see the BHR data that's being collected?</div><div><br></div><div>A: Two part answer:</div><div><br></div><div>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.</div><div><br></div><div>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 <a href="https://github.com/squarewave/bhr.html">https://github.com/squarewave/bhr.html</a> and <a href="http://queze.net/bhr/test/">http://queze.net/bhr/test/</a> 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.)</div><div><br></div><div>Q: What's the difference between TelemetryStopwatch and UserInteractions?</div><div><br></div><div>While the APIs look similar, the end results are very different.</div><div><br></div><div> TelemetryStopwatch will ultimately add a value to a Telemetry Histogram.</div><div><br></div><div>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 bonus).</div><div><br></div><div>Q: I have questions, concerns or opinions that aren't articulated here in this FAQ. What do I do about that?</div><div><br></div><div>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.</div><div><br></div><div>All the best,</div><div><br></div><div>-Mike (:mconley)<br></div></div>