diff options
Diffstat (limited to 'toolkit/components/glean/docs/user/geckoview_streaming_migration.md')
| -rw-r--r-- | toolkit/components/glean/docs/user/geckoview_streaming_migration.md | 262 |
1 files changed, 0 insertions, 262 deletions
diff --git a/toolkit/components/glean/docs/user/geckoview_streaming_migration.md b/toolkit/components/glean/docs/user/geckoview_streaming_migration.md deleted file mode 100644 index 6dede3e90e..0000000000 --- a/toolkit/components/glean/docs/user/geckoview_streaming_migration.md +++ /dev/null @@ -1,262 +0,0 @@ -# Migrating Telemetry Collected via Geckoview Streaming to Glean - -With Geckoview Streaming (GVST) having been deprecated, -this is a guide to migrating collections to [Glean][book-of-glean] -via [Firefox on Glean](../index.md). - -```{contents} -``` - -## Before we Begin - -You should familiarize yourself with the guide on -[Adding New Metrics to Firefox Desktop](./new_definitions_file.md). - -You should also read through the guide for -[Migrating Metrics from Legacy Telemetry to Glean](./migration.md). - -This guide assumes some basic familiarity with the above. -The [Glean book][book-of-glean] has a full API reference, as well. - -## Process - -There are 3 main steps: - -1. Move the metric definition and make necessary updates -2. Update the call to use the Glean API -3. Update the tests to use the Glean test API - -### Move and Update the Metric Definition - -Existing metrics that make use of the GVST will already have a fully specified YAML -entry that we will use as a starting point. -This is convenient, but we want to make some minor updates rather than take it fully as is. -At a minimum we need to move the definition out of the -[Geckoview metrics.yaml][gv-metrics-yaml] file and change from GVST to [GIFFT](./gifft.md). -It can go into whichever metrics.yaml file you feel is most appropriate. -If an appropriate one does not exist, create a new one [following this guide][new-yaml]. -Completely remove the metric definition from the Geckoview `metrics.yaml`. - -For all metric types other than `labeled counters` the first step is to change the key -of the `gecko_datapoint` entry to `telemetry_mirror`. -Next, update the value as per the rules outlined in the [GIFFT guide][telemetry-mirror-doc]. -This change is required to keep data flowing in the Legacy Telemetry version of the metric. -Doing so will ensure that downstream analyses do not break unintentionally. -It is not necessary to modify the [Histograms.json][histograms-json] or -[Scalars.yaml][scalars-yaml] file. - -To migrate `labeled counters` instead fully remove the `gecko_datapoint` entry. -Note that our overall treatment of this type is slightly different. - -Next add the bug that covers the migration to the `bugs` field. -Update the `description` field as well to indicate the metric used to be collected -via the Geckoview Streaming API. Other fields should be updated as makes sense. -For example, you may need to update the field for `notification_emails`. -Since you are not changing the collection a new data review is not necessary. -However, if you notice a metric is set to expire soon and it should continue to be collected, -complete a [data review renewal][dr-renewal] form. - -Do not change the name or metric type. -**If you need to change or one both you are creating a new collection.** - -### Update Calls to Use the Glean API - -The next step is to update the metric calls to the Glean API. -Fortunately, for the vast matjority of metricsthis is a 1:1 swapout, -or for `labeled counters` (which are `categorical histograms` in legacy) we add a second call. -We identify the Glean API, remove the old call, and put in its place the Glean call. -You can find a full API reference in the [Glean][book-of-glean], but we'll look at how to record -values for the types that have existing GVST metrics. - -One way to mentally organize the metrics is to break them into two groups, those that are set, -and those that are accumulated to. As when you use the Legacy Telemetry API for GVST, -they are invoked slightly differently. - -To record in C++, you need to include `#include "mozilla/glean/GleanMetrics.h"`. -In Javascript, it is extremely unlikely that you will not already have access to `Glean`. -If you do not, please reach out to a Data Collection Tools team member on -[the #glean:mozilla.org Matrix channel](https://chat.mozilla.org/#/room/#glean:mozilla.org). - -Let's try a few examples. - -#### Migrating a Set Value (string) in C++ - -Let's look at the case of the Graphics Adaptor Vendor ID. -This is a String, -and it's recorded via GVST in C++ - -GVST YAML entry (slightly truncated): - -```YAML -geckoview: - version: - description: > - The version of the Gecko engine, example: 74.0a1 - type: string - gecko_datapoint: gecko.version -``` - -And this is recorded: - -```CPP -Telemetry::ScalarSet(Telemetry::ScalarID::GECKO_VERSION, - NS_ConvertASCIItoUTF16(gAppData->version)); -``` - -To migrate this, let's update our YAML entry, again moving it out of the GVST -metrics.yaml into the most appropriate one: - -```YAML -geckoview: - version: - description: > - The version of the Gecko engine, example: 74.0a1 - (Migrated from geckoview.gfx.adapter.primary) - type: string - telemetry_mirror: GECKO_VERSION -``` - -Notice how we've checked all of our boxes: - -* Made sure our category makes sense -* Changed gecko_datapoint to telemetry_mirror -* Updated the description to note that it was migrated from another collection -* Kept the type identical. - -Now we can update our call: - -```CPP -mozilla::glean::geckoview::version.Set(nsDependentCString(gAppData->version)); -``` - -#### Migrating a Labeled Counter in C++ - -Let's look at probably the most complicated scenario, one where we need to accumulate -to a labeled collection. Because the glean `labeled counter` and legacy `categorical histogram` -type do not support GIFFT, we will add a second call. -Let's take a look at an elided version of how this would be done with GVST: - -```CPP -switch (aResult.as<NonDecoderResult>()) { - case NonDecoderResult::SizeOverflow: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::size_overflow); - return; - case NonDecoderResult::OutOfMemory: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::out_of_memory); - return; - case NonDecoderResult::PipeInitError: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::pipe_init_error); - return; -} -``` - -And we update it by adding a call with the FOG API: - -```CPP -switch (aResult.as<NonDecoderResult>()) { - case NonDecoderResult::SizeOverflow: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::size_overflow); - mozilla::glean::avif::decode_result.EnumGet(avif::DecodeResult::eSizeOverflow).Add(); - return; - case NonDecoderResult::OutOfMemory: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::out_of_memory); - mozilla::glean::avif::decode_result.EnumGet(avif::DecodeResult::eOutOfMemory).Add(); - return; - case NonDecoderResult::PipeInitError: - AccumulateCategorical(LABELS_AVIF_DECODE_RESULT::pipe_init_error); - mozilla::glean::avif::decode_result.EnumGet(avif::DecodeResult::ePipeInitError).Add(); - return; -} -``` - -#### Migrating an Accumulated Value (Histogram) in Javascript - -Javascript follows the same pattern. Consider the case when want to record the number -of uniqiue site origins. Here's the original JS implementation: - -```Javascript -let originCount = this.computeSiteOriginCount(aWindows, aIsGeckoView); -let histogram = Services.telemetry.getHistogramById( - "FX_NUMBER_OF_UNIQUE_SITE_ORIGINS_ALL_TABS", -); - -if (!this._lastRecordSiteOrigin) { - this._lastRecordSiteOrigin = currentTime; -} else if (currentTime >= this._lastRecordSiteOrigin + this.min_interval) { - this._lastRecordSiteOrigin = currentTime; - - histogram.add(originCount); -} -``` - -And here is the direct Glean version - -```Javascript -let originCount = this.computeSiteOriginCount(aWindows, aIsGeckoView); - -if (!this._lastRecordSiteOrigin) { - this._lastRecordSiteOrigin = currentTime; -} else if (currentTime >= this._lastRecordSiteOrigin + this.min_interval) { - this._lastRecordSiteOrigin = currentTime; - - Glean.tabs.uniqueSiteOriginsAllTabs.accumulateSamples([originCount]); -} - -``` - -Note that we don't have to call into Services to get the histogram object. - -### Update the tests to use the Glean test API - -The last piece is updating tests. If tests don't exist -(which is often the case since testing metrics collected via GVST can be challenging), -we recommend that you write them as the -[the Glean test API is quite straightforward](./instrumentation_tests.md). - -The main test method is `testGetValue()`. Returning to our earlier example of -Number of Unique Site Origins, in a Javascript test we can invoke: - -```Javascript -let result = Glean.tabs.uniqueSiteOriginsAllTabs.testGetValue(); - -// This collection is a histogram, we can check the sum for this test -Assert.equal(result.sum, 144); -``` - -If your collection is in a child process, it can be helpful to invoke -`await Services.fog.testFlushAllChildren();` - -If you wish to write a C++ test, `testGetValue()` is also our main method: - -```CPP -#include "mozilla/glean/GleanMetrics.h" - -ASSERT_EQ(1, - mozilla::glean::avif::image_decode_result - .EnumGet(avif::DecodeResult::eSizeOverflow) - .TestGetValue() - .unwrap() - .ref()); - -ASSERT_EQ(3, - mozilla::glean::avif::image_decode_result - .EnumGet(avif::DecodeResult::eOutOfMemory) - .TestGetValue() - .unwrap() - .ref()); - -ASSERT_EQ(0, - mozilla::glean::avif::image_decode_result - .EnumGet(avif::DecodeResult::ePipeInitError) - .TestGetValue() - .unwrap() - .ref()); -``` - -[book-of-glean]: https://mozilla.github.io/glean/book/index.html -[gv-metrics-yaml]: https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/geckoview/streaming/metrics.yaml -[histograms-json]: https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Histograms.json -[scalars-yaml]: https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml -[new-yaml]: ./new_definitions_file.md#where-do-i-define-new-metrics-and-pings -[dr-renewal]: https://github.com/mozilla/data-review/blob/main/renewal_request.md -[telemetry-mirror-doc]: https://firefox-source-docs.mozilla.org/toolkit/components/glean/user/gifft.html#the-telemetry-mirror-property-in-metrics-yaml |