1243603 - Add telemetry to record when Firefox is launched with an external URL

Status: RESOLVED FIXED

(Firefox :: Shell Integration, enhancement, P2)

Description

[Justin Dolske [:Dolske]]

Being the default browser on a user's system only really matters when the user it doing something in other apps / parts of the OS that cause things to be opened in the default browser. (EG, clicking a link in an email app, or opening a local .html file).

We have some indications that being the default browser may not have a large impact on usage, which would imply that users are not opening links/files from outside the browser as much as they have in the past.

Some telemetry to record these instances would help us confirm that's the case, and understand modern browser usage.

I haven't thought about it deeply, but I think the minimal 2 bits of data to record would be:

* Was the current Firefox session started by launching as a default handler?
* Post-startup, has this Firefox session been used to open something as a default handler?

I could also imagine these being counters instead of flags.

(Can we tell the difference between Firefox being launched as a default handler, and the user manually invoking it w/ a url from the command line? I'd suspect not, but also would suspect that such usage isn't common enough to matter.)

Comment 1

[Jared Wein [:jaws] (please needinfo? me)]

Interesting as well, though possibly tangential to comment #0, would be to know how the session was started (start menu, taskbar, desktop shortcut). We could probably do this by adding an extra argument to the executable based on where the installer creates the shortcut.

Shortcuts created by the installer on the desktop could have 'firefox.exe --origin desktop', taskbar having 'firefox.exe --origin taskbar', and startmenu having 'firefox.exe --origin startmenu' (if this last one is possible). 

User created shortcuts and auto-generated start menu items would be missing these extra origin annotations. If this number was significantly high, we could add additional code to Firefox to count any user-created desktop shortcuts and possibly infer some more data from that.

Comment 2

[Rachel Tublitz [:rachel]]

Romain; would you see this as being valuable to prioritize?

Comment 3

[Romain Testard [:RT]]

A couple comments:
-Regarding comment #0: Have you looked into the probe browser.engagement.navigation.urlbar which "counts URI loads triggered in a subsession from the urlbar (awesomebar), broken down by the originating action". I could not find details of what "originating action is though perhaps you can see it in the code? If not yet available it feels worth adding the "record when Firefox is launched with an external URL" information to this scalar so we can breakdown URL loads per origins

• Regarding "Knowing how the session was started": I like this idea and I'd be curious about what this would tell us. It may be something that informs onboarding actions such as advising Win10 users on how to add a taskbar shortcut (we can't add shortcuts automatically anymore on Win10). Probably we need another bug for this?

Comment 4

[Sam Foster [:sfoster] (he/him)]

It looks like we'll need at least 2 steps here, which might make sense to break out into separate bugs and make this the meta bug. As a first step, we can instrument where the information we need already exists. I think this includes protocol and file/mime-type handling where - if I understand correctly - we should be able to just look at the nsICommandLineHandler info. Some of the other requirements will need more work to both the installer and the browser to make the requested details available to telemetry.

:rachel, I can make a first pass at sketching out what we want to end up with in terms of the telemetry data types but maybe we can chat about how to move this forward?

Comment 5

[Rachel Tublitz [:rachel]]

Hi Sam,

Adam is going to be the point person here for this work. Adam, when you have some time can you work with Sam to see how to move this one along?

Comment 6

[Sam Foster [:sfoster] (he/him)]

I've added a proposal to the google doc for how we might structure this using Event Telemetry.

I don't know Windows well enough to be sure some of these requests if technically feasible. Is there even a way to know if an application was launched via a user-created shortcut vs. the .exe directly? Broadly, the structure seems to map to the requirements pretty well though, and if we can find the right entry point for the instrumentation, we should be able to accomodate the perf. team request for startup time measurement.

We could get started with some of the requests that don't need a lot of installer or feature work, initiate a data review and start collecting those data points while we work out the details on the rest.

Comment 7

[Adam Gashlin (he/him) [:agashlin] (ex-moco)]

It should be possible to use the existing switches like -osint -url and -os-restarted to track the major ways that the OS launches us. We could add switches to attribute startups to our various shortcuts on the desktop, start menu, or taskbar (quick launch is obsolete). I don't think there could be a way to distinguish between any of the ways of launching Firefox that we did not create, though, at least on Windows, so the different user-created shortcuts would look the same as directly launching the .exe, or if the user copies one of our shortcuts it would be indistinguishable from that.

The biggest win will probably just be to report whether we were launched with a URL, I think you're right that the place to look for this would be where we handle the -url arg, but I have never worked with that area of the code. It may make sense to check for -osint as well to be extra confident (I think it might still survive to that point but I haven't checked), we use that whenever registering URL or file handlers with the OS so bad escaping won't cause other operations. This should handle the default browser cases, which I think is what we're mostly interested in.

-os-restarted (to detect automatic restart, only on Windows currently) is removed in nsAppRunner, but it does set the flag appinfo.restartedByOS. I'm surprised to not find even an expired telemetry probe tracking that, I thought we had one when we were rolling it out.

I haven't looked over our shortcut stuff lately, so I'm not too clear on the details of when we install or update the various kinds of shortcuts (desktop, start menu, taskbar) on Windows, and I know even less about other platforms. But I expect it will be difficult to install identifying switches into all those places with high reliability.

For new installs, I think it would go in the CreateShorcut calls starting here, and it should also go in ShowShortcuts (for a pre-Win10 mechanism).

Updating existing installs would be a step alongside the various shortcut fix and migration macros. Possibly elsewhere.

One complication is that on Windows some shortcuts draw from the same file in the start menu, so I'm not sure what happens if we start duplicating it to try to use a different switch in each case.

I'll keep an eye out for any questions!

Comment 8

[Adam Gashlin (he/him) [:agashlin] (ex-moco)]

While it is possible on Windows to get an idea of what process launched Firefox, we'd have to plumb this through the launcher process somehow, and I'm not sure how reliable it would be.

I think the nsICommandLineHandler in browser will see remote requests as well, so that should also handle any URLs/files that open in Firefox after it started running. If we want to distinguish remoting from the initial link that opened Firefox, I'm not sure where we'd do that.

Comment 9

[Sam Foster [:sfoster] (he/him)]

Unassigning myself for now in case someone else can get to this before me.

Comment 10

[Nick Alexander :nalexander [he/him]]

sfoster: shong: could I ask for a fresh opinion on events vs scalars for collecting a subset of this telemetry? To support some experimentation with setting Firefox as the default PDF handler on Windows, I intend to collect two rows from Sam's document, namely some data about when Firefox is launched:

as protocol handler
as file-type handler

Over in Bug 1685213, Adam implemented part of that table -- now called os.environment.launch_method -- as a scalar: see https://searchfox.org/mozilla-central/rev/9a5f36b0ddb9cb8ae556fc5b45f8ccea0f0da6f8/browser/components/BrowserGlue.jsm#2465-2468. This was in response to the following comment by Su:

it sounds like you're planning to implement this as an event. any specific reason? it seems to me that having this as a scalar inside main pings makes sense. it would make analysis much more straightforward.

Do you have an updated opinion on scalars vs events for this use case?

Comment 11

[Sam Foster [:sfoster] (he/him)]

(In reply to Nick Alexander :nalexander [he/him] from comment #10)

it sounds like you're planning to implement this as an event. any specific reason? it seems to me that having this as a scalar inside main pings makes sense. it would make analysis much more straightforward.

Do you have an updated opinion on scalars vs events for this use case?

Making analysis much more straightforward sounds like an excellent reason to use a scalar.

Comment 12

[Romain Testard [:RT]]

(In reply to Nick Alexander :nalexander [he/him] from comment #10)

sfoster: shong: could I ask for a fresh opinion on events vs scalars for collecting a subset of this telemetry? To support some experimentation with setting Firefox as the default PDF handler on Windows, I intend to collect two rows from Sam's document, namely some data about when Firefox is launched:

as protocol handler
as file-type handler

Could we potentially identify these 2 conditions even if Firefox was opened already with a way to segment them:

• A new tab is opened as a result of a protocol handler call initiated from outside Firefox with details if this call initiated the session or not
• A new tab is opened as a result of a file-type handler call initiated from outside Firefox with details if this call initiated the session or not

Comment 13

[Nick Alexander :nalexander [he/him]]

(In reply to Romain Testard [:RT] from comment #12)

(In reply to Nick Alexander :nalexander [he/him] from comment #10)

sfoster: shong: could I ask for a fresh opinion on events vs scalars for collecting a subset of this telemetry? To support some experimentation with setting Firefox as the default PDF handler on Windows, I intend to collect two rows from Sam's document, namely some data about when Firefox is launched:

as protocol handler
as file-type handler

Could we potentially identify these 2 conditions even if Firefox was opened already with a way to segment them:

• A new tab is opened as a result of a protocol handler call initiated from outside Firefox with details if this call initiated the session or not
• A new tab is opened as a result of a file-type handler call initiated from outside Firefox with details if this call initiated the session or not

Romain -- the technical path of least resistance is to add a counter, somewhat like os.environment.launch_method, that increments each time Firefox handles a protocol or file-type request. This doesn't make it easy to determine if Firefox was launched to handle such a request. Am I correct that you're asking for os.environment.launch_method to be generalized, perhaps to:

• "Desktop"
• "StartMenu" (including pins),
• "Taskbar"
• "OtherShortcut"
• "ForFileType"
• "ForProtocol"
• "Other"
  It's not clear to me how to generalize the launch method to include the file type or the protocol of the launch itself, but once we're clear on your request I can work through how to represent it in telemetry.

Comment 14

[Nick Alexander :nalexander [he/him]]

Attachment: Bug 1243603 - Telemetry for when Windows invokes Firefox to handle a registered file type or protocol. r?gijs

The -osint flag is used as the signal that Windows is invoking
Firefox to handle a file type or protocol. The -osint flag was
introduced in order to mitigate security breaches due to poor argument
quoting (by consumers invoking Firefox); to use it for this new
purpose, it must be preserved for downstream consumers to react to.
Alternately, some marker of the flag could be maintained. Since the
flag needs to transit through the launcher process, I've elected to
simply not strip it as we validate command lines, and to accommodate
it further downstream. (It looks like Thunderbird already
accommodates -osint: see
https://searchfox.org/comm-central/rev/3e8f926de9ea09945b237177eb6d489c70318f0e/mail/components/MessengerContentHandler.jsm#568.)

The telemetry in this patch achieves two purposes. The first is to
count the number of times Firefox is invoked to handle a registered
file type or protocol: for this, a new keyed uint scalar was added.
File types start with a ".", just like on Windows; protocols
(equivalently, the schemes used to identify them) do not start with a
".".

The second is to identify times when Firefox is launched (i.e., it was
not already running) to handle a registered file type or protocol.
This generalizes the existing os.environment.launch_method with the
new value ToHandle and additional data in the
os.environment.launch_method_to_handle string scalar, which records
the file type or protocol.

The command line state STATE_INITIAL_LAUNCH is used to discriminate
launching from invoking.

Comment 15

[Nick Alexander :nalexander [he/him]]

Attachment: Bug 1243603 - Post: Remove useless `-osint` checks. r?gijs

EnsureCommandLineSafe
doesn't allow -p with -osint, so these checks are useless.

Depends on D132288

Comment 16

[Nick Alexander :nalexander [he/him]]

Attachment: Bug 1243603 - Post: Add stub documentation for command line parameters. r?gijs

The small idea here is to set down some notes about -osint. The
larger idea is to provide a location for future improvements.

Depends on D132543

Comment 17

[Nick Alexander :nalexander [he/him]]

Attachment: 1697875-data-review-1.md

Comment 18

[Nick Alexander :nalexander [he/him]]

Attachment: 1243603-data-review-1.md

Comment 19

[Nick Alexander :nalexander [he/him]]

jimt: I propose the following scalar probes for counting the times Firefox was launched/started and invoked/already-running-and-asked to open various file extensions and protocol handlers. Can you verify that this is enough for our immediate purposes?

No need for Su or Romain to respond at this point, I think.

Comment 20

[Nick Alexander :nalexander [he/him]]

Comment on attachment 9253305 [details]
1243603-data-review-1.md

I didn't realize Jared was PTO. :chutten, can you data review this?

Comment 21

[Chris H-C :chutten]

Comment on attachment 9253305 [details]
1243603-data-review-1.md

DATA COLLECTION REVIEW RESPONSE:

Is there or will there be documentation that describes the schema for the ultimate data set available publicly, complete and accurate?

Yes.

Is there a control mechanism that allows the user to turn the data collection on and off?

Yes. This collection is Telemetry so can be controlled through Firefox's Preferences.

If the request is for permanent data collection, is there someone who will monitor the data over time?

No. This collection will expire in six months.

Using the category system of data types on the Mozilla wiki, what collection type of data do the requested measurements fall under?

Category 2, Interaction.

Is the data collection request for default-on or default-off?

Default on for all channels.

Does the instrumentation include the addition of any new identifiers?

No.

Is the data collection covered by the existing Firefox privacy notice?

Yes.

Does the data collection use a third-party collection tool?

No.

---

Result: datareview+

Comment 22

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/3526fd3304fd
Telemetry for when Windows invokes Firefox to handle a registered file type or protocol. r=Gijs
https://hg.mozilla.org/integration/autoland/rev/d983e3c3863e
Post: Remove useless `-osint` checks. r=Gijs
https://hg.mozilla.org/integration/autoland/rev/009a1ae6b943
Post: Add stub documentation for command line parameters. r=Gijs

Comment 23

[Atila Butkovits]

https://hg.mozilla.org/mozilla-central/rev/3526fd3304fd
https://hg.mozilla.org/mozilla-central/rev/d983e3c3863e
https://hg.mozilla.org/mozilla-central/rev/009a1ae6b943

Comment 24

[Andrei Purice]

QA has performed a check on the latest version of Firefox Nightly 97.0a1 (2021-12-14) and can confirm that the following telemetry data is present : os.environment.launched_to_handle, os.environment.invoked_to_handle and os.environment.is_default_handler and that the data shown by these three were correct.
Tests were done on Windows 10.