Merge mozilla-mobile#4242

4242: Allow generating docs for Glean metrics r=Dexterp37 a=Dexterp37 The docs are written, at build-time, to '$project/docs/metrics.md'. This additionally enables automatic doc generation for the following components: lib-crash, storage-sync. Bonus: add a note to engine-gecko-nightly's readme to explicitly require a data-review for products using it. @pocmo - r? for the changes to lib-crash @linacambridge - r? for the changes to browser-sync **Note**: whenever new metrics are added, the build system will automatically update the docs so that the dev can simply commit the changes. Co-authored-by: Alessio Placitelli <alessio.placitelli@gmail.com>
Amejia481 · Sep 3, 2019 · 648ed1c · 648ed1c
2 parents e77dec0 + c86fea4
commit 648ed1c
Show file tree

Hide file tree

Showing 8 changed files with 148 additions and 10 deletions.
diff --git a/components/browser/engine-gecko-nightly/README.md b/components/browser/engine-gecko-nightly/README.md
@@ -14,6 +14,9 @@ implementation "org.mozilla.components:browser-engine-gecko-nightly:{latest-vers
 
 ### Integration with the Glean SDK
 
+#### Before using this component
+Products sending telemetry and using this component *must request* a data-review following [this process](https://wiki.mozilla.org/Firefox/Data_Collection).
+
 The [Glean SDK](../../../components/service/glean/README.md) can be used to collect [Gecko Telemetry](https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/index.html).
 Applications using both this component and the Glean SDK should setup the Gecko Telemetry delegate
 as shown below:

diff --git a/components/browser/storage-sync/README.md b/components/browser/storage-sync/README.md
@@ -2,6 +2,11 @@
 
 A syncable implementation of `concept-storage` backed by [application-services' Places lib](https://github.com/mozilla/application-services).
 
+## Before using this component
+Products sending telemetry and using this component *must request* a data-review following [this process](https://wiki.mozilla.org/Firefox/Data_Collection).
+This component provides data collection using the [Glean SDK](https://mozilla.github.io/glean/book/index.html).
+The list of metrics being collected is available in the [metrics documentation](docs/metrics.md).
+
 ### Setting up the dependency
 
 Use Gradle to download the library from [maven.mozilla.org](https://maven.mozilla.org/) ([Setup repository](../../../README.md#maven-repository)):

diff --git a/components/browser/storage-sync/build.gradle b/components/browser/storage-sync/build.gradle
@@ -76,4 +76,5 @@ dependencies {
 apply from: '../../../publish.gradle'
 ext.configurePublish(config.componentsGroupId, archivesBaseName, project.ext.description)
 
+ext.gleanGenerateMarkdownDocs = true
 apply from: '../../service/glean/scripts/sdk_generator.gradle'
diff --git a/components/browser/storage-sync/docs/metrics.md b/components/browser/storage-sync/docs/metrics.md
@@ -0,0 +1,48 @@
+<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
+
+# Metrics
+This document enumerates the metrics collected by this project.
+This project may depend on other projects which also collect metrics.
+This means you might have to go searching through the dependency tree to get a full picture of everything collected by this project.
+Sorry about that.
+
+# Pings
+
+ - [bookmarks_sync](#bookmarks_sync)
+ - [history_sync](#history_sync)
+
+
+## bookmarks_sync
+A ping sent for every bookmarks sync. It doesn't include the `client_id` because it reports a hashed version of the user's Firefox Account ID.
+
+The following metrics are added to the ping:
+
+| Name | Type | Description | Data reviews | Extras | Expiration |
+| --- | --- | --- | --- | --- | --- |
+| bookmarks_sync.failure_reason |[labeled_string](https://mozilla.github.io/glean/book/user/metrics/labeled_strings.html) |Records bookmark sync failure reasons.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.finished_at |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |Records when the bookmark sync finished.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.incoming |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Records incoming bookmark record counts.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.outgoing |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Records outgoing bookmark record counts.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.outgoing_batches |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |Records the number of batches needed to upload all outgoing records.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.remote_tree_problems |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Records counts for structure problems and divergences in the remote bookmarks tree. These are documented in https://github.com/mozilla/dogear/blob/fbade15f2a4f11215e30b8f428a0a8df3defeaec/src/tree.rs#L1273-L1294.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.started_at |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |Records when the bookmark sync started.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| bookmarks_sync.uid |[string](https://mozilla.github.io/glean/book/user/metrics/string.html) |The user's hashed Firefox Account ID.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+
+## history_sync
+A ping sent for every history sync. It doesn't include the `client_id` because it reports a hashed version of the user's Firefox Account ID.
+
+The following metrics are added to the ping:
+
+| Name | Type | Description | Data reviews | Extras | Expiration |
+| --- | --- | --- | --- | --- | --- |
+| history_sync.failure_reason |[labeled_string](https://mozilla.github.io/glean/book/user/metrics/labeled_strings.html) |Records why the history sync failed: either due to an authentication error, unexpected exception, or other error. The error strings are truncated and sanitized to omit PII, like URLs and file system paths.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.finished_at |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |Records when the history sync finished. This includes the time to download, apply, and upload all records.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.incoming |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Records incoming history record counts. `applied` is the number of incoming history pages that were successfully stored or updated in the local database. `failed_to_apply` is the number of pages that were ignored due to errors. `reconciled` is the number of pages with new visits locally and remotely, and had their visits merged.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.outgoing |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Records outgoing history record counts. `uploaded` is the number of records that were successfully sent to the server. `failed_to_upload` is the number of records that weren't uploaded, and will be retried on the next sync.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.outgoing_batches |[counter](https://mozilla.github.io/glean/book/user/metrics/counter.html) |Records the number of batches needed to upload all outgoing records. The Sync server has a hard limit on the number of records (and request body bytes) on the number of records that can fit into a single batch, and large syncs may require multiple batches.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.started_at |[datetime](https://mozilla.github.io/glean/book/user/metrics/datetime.html) |Records when the history sync started.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+| history_sync.uid |[string](https://mozilla.github.io/glean/book/user/metrics/string.html) |The user's hashed Firefox Account ID.  |[1](https://github.com/mozilla-mobile/android-components/pull/3092)||never |
+
+
+<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
+
diff --git a/components/lib/crash/README.md b/components/lib/crash/README.md
@@ -92,7 +92,8 @@ CrashReporter(
 ### Sending crash reports to Glean
 
 [Glean](https://docs.telemetry.mozilla.org/concepts/glean/glean.html) is a new way to collect telemetry by Mozilla. 
-This will record crash counts as a labelled counter with each label corresponding to a specific type of crash (`native_code_crash`, and `unhandled_exception`, currently). The list of collected metrics is available in the [metrics.yaml file](metrics.yaml). 
+This will record crash counts as a labeled counter with each label corresponding to a specific type of crash (`native_code_crash`, and `unhandled_exception`, currently).
+The list of collected metrics is available in the [metrics.yaml file](metrics.yaml), with their documentation [living here](docs/metrics.md).
 Due to the fact that Glean can only be recorded to in the main process and lib-crash runs in a separate process when it runs to handle the crash, 
 lib-crash persists the data in a file format and then reads and records the data from the main process when the application is next run since the `GleanCrashReporterService`
 constructor is loaded from the main process.
@@ -108,7 +109,7 @@ CrashReporter(
 ```
 
 ⚠️ Note: In order for Glean to be able to record to metrics, it **MUST** be initialized within the application before instantiating the `GleanCrashReporterService` and registering it with the `CrashReporter`.
-⚠️ Note: Applications using the `GleanCrashReporterService` are required to undergo Data Collection Review for the crash counts that they will be collecting.
+⚠️ Note: Applications using the `GleanCrashReporterService` are **required** to undergo [Data Collection Review](https://wiki.mozilla.org/Firefox/Data_Collection) for the crash counts that they will be collecting.
 
 ### Showing a crash reporter prompt
 

diff --git a/components/lib/crash/build.gradle b/components/lib/crash/build.gradle
@@ -55,6 +55,7 @@ dependencies {
     testImplementation Dependencies.testing_coroutines
 }
 
+ext.gleanGenerateMarkdownDocs = true
 apply from: '../../../components/service/glean/scripts/sdk_generator.gradle'
 apply from: '../../../publish.gradle'
 ext.configurePublish(config.componentsGroupId, archivesBaseName, project.ext.description)
diff --git a/components/lib/crash/docs/metrics.md b/components/lib/crash/docs/metrics.md
@@ -0,0 +1,25 @@
+<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
+
+# Metrics
+This document enumerates the metrics collected by this project.
+This project may depend on other projects which also collect metrics.
+This means you might have to go searching through the dependency tree to get a full picture of everything collected by this project.
+Sorry about that.
+
+# Pings
+
+ - [metrics](#metrics)
+
+
+## metrics
+This is a built-in ping that is assembled out of the box by the Glean SDK.
+See the Glean SDK documentation for the [`metrics` ping](https://mozilla.github.io/glean/book/user/pings/metrics.html).
+The following metrics are added to the ping:
+
+| Name | Type | Description | Data reviews | Extras | Expiration |
+| --- | --- | --- | --- | --- | --- |
+| crash_metrics.crash_count |[labeled_counter](https://mozilla.github.io/glean/book/user/metrics/labeled_counters.html) |Counts the number of crashes that occur in the application.  This measures only the counts of each crash in association with the labeled type of the crash. The labels correspond to the types of crashes handled by lib-crash.  |[1](https://bugzilla.mozilla.org/show_bug.cgi?id=1553935#c3)||never |
+
+
+<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. -->
+
diff --git a/components/service/glean/scripts/sdk_generator.gradle b/components/service/glean/scripts/sdk_generator.gradle
@@ -21,7 +21,7 @@ import org.gradle.api.internal.artifacts.ArtifactAttributes
 // so that it will be shared between all libraries that use Glean.  This is
 // important because it is approximately 300MB in installed size.
 
-String GLEAN_PARSER_VERSION = "1.3.0"
+String GLEAN_PARSER_VERSION = "1.4.0"
 // The version of Miniconda is explicitly specified.
 // Miniconda3-4.5.12 is known to not work on Windows.
 String MINICONDA_VERSION = "4.5.11"
@@ -170,6 +170,18 @@ if (project.ext.has("allowMetricsFromAAR")) {
     }
 }
 
+def gleanTaskNamePrefix = "generateMetricsSourceFor"
+
+// A shared function to get the Python command line executable.
+ext.gleanGetPythonCommand = {
+    // Note that the command line is OS dependant: on linux/mac is Miniconda3/bin/python.
+    if (Os.isFamily(Os.FAMILY_WINDOWS)) {
+        return new File(GLEAN_MINICONDA_DIR, "python")
+    }
+
+    return new File(GLEAN_MINICONDA_DIR, "bin/python")
+}
+
 // Generate the Metrics API
 ext.gleanGenerateMetricsAPI = {
     variant ->
@@ -183,7 +195,7 @@ ext.gleanGenerateMetricsAPI = {
     def originalPackageName = buildConfigProvider.get().getBuildConfigPackageName()
 
     def fullNamespace = "${originalPackageName}.GleanMetrics"
-    def generateKotlinAPI = task("generateMetricsSourceFor${variant.name.capitalize()}", type: Exec) {
+    def generateKotlinAPI = task("$gleanTaskNamePrefix${variant.name.capitalize()}", type: Exec) {
         description = "Generate the Kotlin code for the Metrics API"
 
         if (project.ext.has("allowMetricsFromAAR")) {
@@ -199,12 +211,7 @@ ext.gleanGenerateMetricsAPI = {
         outputs.dir sourceOutputDir
 
         workingDir  rootDir
-        // Note that the command line is OS dependant: on linux/mac is Miniconda3/bin/python.
-        if (Os.isFamily(Os.FAMILY_WINDOWS)) {
-            commandLine new File(GLEAN_MINICONDA_DIR, "python")
-        } else {
-            commandLine new File(GLEAN_MINICONDA_DIR, "bin/python")
-        }
+        commandLine gleanGetPythonCommand()
 
         def gleanNamespace = "mozilla.components.service.glean"
         if (project.ext.has("gleanNamespace")) {
@@ -273,6 +280,53 @@ ext.gleanGenerateMetricsAPI = {
     }
 }
 
+// Generate the Metrics docs, if requested.
+if (project.ext.has("gleanGenerateMarkdownDocs")) {
+    task gleanGenerateMetricsDocs(type: Exec) {
+        description = "Generate the Markdown docs for the collected metrics"
+
+        outputs.dir "$projectDir/docs"
+        workingDir rootDir
+        commandLine gleanGetPythonCommand()
+
+        args "-c"
+        args runPythonScript
+        args "glean_parser"
+        args GLEAN_PARSER_VERSION
+        args "translate"
+        args "-f"
+        args "markdown"
+        args "-o"
+        args "$projectDir/docs"
+        args "$projectDir/metrics.yaml"
+        args "$projectDir/pings.yaml"
+
+        doFirst {
+            inputs.files.forEach{ file ->
+                project.logger.lifecycle("Glean SDK - generating docs for ${file.path} in $projectDir/docs")
+            }
+        }
+
+        // Only show the output if something went wrong.
+        ignoreExitValue = true
+        standardOutput = new ByteArrayOutputStream()
+        errorOutput = standardOutput
+        doLast {
+            if (execResult.exitValue != 0) {
+                throw new GradleException("Process '${commandLine}' finished with non-zero exit value ${execResult.exitValue}:\n\n${standardOutput.toString()}")
+            }
+        }
+    }
+
+    // Attach the docs generation task to the code generation task, to make sure
+    // we generate docs, if we're asked for it.
+    tasks.whenTaskAdded { task ->
+        if (task.name.startsWith(gleanTaskNamePrefix)) {
+            task.dependsOn(gleanGenerateMetricsDocs)
+        }
+    }
+}
+
 if (android.hasProperty('applicationVariants')) {
     android.applicationVariants.all(ext.gleanGenerateMetricsAPI)
 } else {