Bug 1932322 - Implement the new collection-enabled API

.circleci/config.yml

@@ -93,6 +93,14 @@ commands:
           name: Run Rust RLB flush test
           command: |
             glean-core/rlb/tests/test-ping-lifetime-flush.sh
+      - run:
+          name: Run Rust RLB enabled-pings test
+          command: |
+            glean-core/rlb/tests/test-enabled-pings.sh
+      - run:
+          name: Run Rust RLB pending-gets-removed test
+          command: |
+            glean-core/rlb/tests/test-pending-gets-removed.sh
 
   install-rustup:
     steps:

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 * General
   * Add methods to access current Glean debugging settings and the list of currently registered pings([Bug 1921976](https://bugzilla.mozilla.org/show_bug.cgi?id=1921976)).
+  * Require `glean_parser` v16.1.0 ([#3006](https://github.com/mozilla/glean/pull/3006))
+  * BREAKING CHANGE: Add new `collection-enabled` mode (and `follows_collection_enabled` setting for pings).
+    This allows to control a subset of pings independently from the Glean-wide `upload-enabled` flag.
+    This deprecates the `setUploadEnabled` API in favor of `setCollectionEnabled`. ([#3006](https://github.com/mozilla/glean/pull/3006))
 * Rust
   * Permit Glean shutdown to interrupt UploadManager Wait tasks ([bug 1928288](https://bugzilla.mozilla.org/show_bug.cgi?id=1928288))
 

Makefile

@@ -157,7 +157,7 @@ docs-python: build-python ## Build the Python documentation
 .PHONY: docs docs-rust docs-swift
 
 docs-metrics: setup-python ## Build the internal metrics documentation
-	$(GLEAN_PYENV)/bin/pip install glean_parser~=15.2
+	$(GLEAN_PYENV)/bin/pip install glean_parser~=16.1
 	$(GLEAN_PYENV)/bin/glean_parser translate --allow-reserved \
 		 -f markdown \
 		 -o ./docs/user/user/collected-metrics \

glean-core/Cargo.toml

@@ -21,7 +21,7 @@ include = [
 rust-version = "1.76"
 
 [package.metadata.glean]
-glean-parser = "15.2.0"
+glean-parser = "16.1.0"
 
 [badges]
 circle-ci = { repository = "mozilla/glean", branch = "main" }

glean-core/android/src/main/java/mozilla/telemetry/glean/Glean.kt

@@ -289,7 +289,7 @@ open class GleanInternalAPI internal constructor() {
     }
 
     /**
-     * Enable or disable Glean collection and upload.
+     * **DEPRECATED** Enable or disable Glean collection and upload.
      *
      * Metric collection is enabled by default.
      *
@@ -300,12 +300,36 @@ open class GleanInternalAPI internal constructor() {
      *
      * When enabling, the core Glean metrics are recreated.
      *
+     * **DEPRECATION NOTICE**:
+     * This API is deprecated. Use `setCollectionEnabled` instead.
+     *
      * @param enabled When true, enable metric collection.
      */
+    @Deprecated("Use `setCollectionEnabled` instead.")
     fun setUploadEnabled(enabled: Boolean) {
         gleanSetUploadEnabled(enabled)
     }
 
+    /**
+     * Enable or disable Glean collection and upload.
+     *
+     * Metric collection is enabled by default.
+     *
+     * When collection is disabled, metrics aren't recorded at all and no data
+     * is uploaded.
+     * **Note**: Individual pings can be enabled if they don't follow this setting.
+     * See `PingType.setEnabled`.
+     *
+     * When disabling, all pending metrics, events and queued pings are cleared.
+     *
+     * When enabling, the core Glean metrics are recreated.
+     *
+     * @param enabled When true, enable metric collection.
+     */
+    fun setCollectionEnabled(enabled: Boolean) {
+        gleanSetUploadEnabled(enabled)
+    }
+
     /**
      * Indicate that an experiment is running. Glean will then add an
      * experiment annotation to the environment which is sent with pings. This

glean-core/android/src/main/java/mozilla/telemetry/glean/private/PingType.kt

@@ -54,6 +54,7 @@ class PingType<ReasonCodesEnum> (
     enabled: Boolean,
     val schedulesPings: List<String>,
     val reasonCodes: List<String>,
+    followsCollectionEnabled: Boolean,
 ) where ReasonCodesEnum : Enum<ReasonCodesEnum>, ReasonCodesEnum : ReasonCode {
     private var testCallback: ((ReasonCodesEnum?) -> Unit)? = null
     private val innerPing: GleanPingType
@@ -68,6 +69,7 @@ class PingType<ReasonCodesEnum> (
             schedulesPings = schedulesPings,
             reasonCodes = reasonCodes,
             enabled = enabled,
+            followsCollectionEnabled = followsCollectionEnabled,
         )
     }
 
@@ -108,4 +110,14 @@ class PingType<ReasonCodesEnum> (
         val reasonString = reason?.let { this.reasonCodes[it.code()] }
         this.innerPing.submit(reasonString)
     }
+
+    /**
+     * Enable or disable a ping.
+     *
+     * Disabling a ping causes all data for that ping to be removed from storage
+     * and all pending pings of that type to be deleted.
+     */
+    fun setEnabled(enabled: Boolean) {
+        this.innerPing.setEnabled(enabled)
+    }
 }

glean-core/android/src/main/java/mozilla/telemetry/glean/testing/GleanTestRule.kt

@@ -79,6 +79,7 @@ class GleanTestRule(
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
         PingType<NoReasonCodes>(
             name = "store2",
@@ -89,6 +90,7 @@ class GleanTestRule(
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
         PingType<NoReasonCodes>(
             name = "store3",
@@ -99,6 +101,7 @@ class GleanTestRule(
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         Glean.resetGlean(

glean-core/android/src/test/java/mozilla/telemetry/glean/GleanTest.kt

@@ -62,7 +62,7 @@ class GleanTest {
 
     @After
     fun resetGlobalState() {
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
     }
 
     @Test
@@ -121,7 +121,7 @@ class GleanTest {
                 sendInPings = listOf("store1"),
             ),
         )
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
 
         stringMetric.set("foo")
         assertNull(stringMetric.testGetValue())
@@ -483,6 +483,7 @@ class GleanTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = listOf(),
+            followsCollectionEnabled = true,
         )
         val stringMetric = StringMetricType(
             CommonMetricData(
@@ -542,12 +543,12 @@ class GleanTest {
         stringMetric.set("TEST VALUE")
         assertEquals("TEST VALUE", stringMetric.testGetValue()!!)
 
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         assertNull(stringMetric.testGetValue())
         stringMetric.set("TEST VALUE")
         assertNull(stringMetric.testGetValue())
 
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
         assertNull(stringMetric.testGetValue())
         stringMetric.set("TEST VALUE")
         assertEquals("TEST VALUE", stringMetric.testGetValue()!!)
@@ -557,10 +558,10 @@ class GleanTest {
     fun `Core metrics should be cleared and restored when disabling and enabling uploading`() {
         assertNotNull(GleanInternalMetrics.os.testGetValue())
 
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         assertNull(GleanInternalMetrics.os.testGetValue())
 
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
         assertNotNull(GleanInternalMetrics.os.testGetValue())
     }
 
@@ -585,7 +586,7 @@ class GleanTest {
             Glean.metricsPingScheduler!!.timer != null,
         )
 
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
 
         // Verify that the workers are still enqueued to show that setting upload enabled to true
         // doesn't affect any already queued workers, since we ask consumers to set upload enabled
@@ -600,7 +601,7 @@ class GleanTest {
         )
 
         // Toggle upload enabled to false
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
 
         // Verify workers have been cancelled
         assertTrue(
@@ -853,6 +854,7 @@ class GleanTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = listOf(),
+            followsCollectionEnabled = true,
         )
         val stringMetric = StringMetricType(
             CommonMetricData(
@@ -871,7 +873,7 @@ class GleanTest {
         Glean.initialize(context, true, config, GleanBuildInfo.buildInfo)
 
         // Glean might still be initializing. Disable upload.
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
 
         // Set data and try to submit a custom ping.
         val testValue = "SomeTestValue"

glean-core/android/src/test/java/mozilla/telemetry/glean/debug/GleanDebugActivityTest.kt

@@ -253,6 +253,7 @@ class GleanDebugActivityTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = listOf(),
+            followsCollectionEnabled = true,
         )
 
         // Set the extra values and start the intent.

glean-core/android/src/test/java/mozilla/telemetry/glean/pings/CustomPingTest.kt

@@ -83,6 +83,7 @@ class CustomPingTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         customPing.submit()
@@ -115,6 +116,7 @@ class CustomPingTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         // Trigger the ping twice.
@@ -174,6 +176,7 @@ class CustomPingTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         // Define a 'click' event
@@ -252,6 +255,7 @@ class CustomPingTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         customPing.submit()

glean-core/android/src/test/java/mozilla/telemetry/glean/pings/DeletionPingTest.kt

@@ -95,7 +95,7 @@ class DeletionPingTest {
         val pendingDeletionRequestDir = File(Glean.getDataDir(), DELETION_PING_DIR)
 
         // Disabling upload generates a deletion ping
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         triggerWorkManager(context)
 
         val request = server.takeRequest(2L, TimeUnit.SECONDS)!!
@@ -107,7 +107,7 @@ class DeletionPingTest {
 
         // Re-setting upload to `false` should not generate an additional ping
         // and no worker should be scheduled.
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
 
         assertFalse(getWorkerStatus(context, PingUploadWorker.PING_WORKER_TAG).isEnqueued)
         // No new file should have been written
@@ -182,7 +182,7 @@ class DeletionPingTest {
         )
 
         // Disabling upload generates a deletion ping
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         triggerWorkManager(context)
 
         val request = server.takeRequest(2L, TimeUnit.SECONDS)!!

glean-core/android/src/test/java/mozilla/telemetry/glean/pings/RidealongPingTest.kt

@@ -72,6 +72,7 @@ class RidealongPingTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = emptyList(),
+            followsCollectionEnabled = true,
         )
 
         Glean.handleBackgroundEvent()

glean-core/android/src/test/java/mozilla/telemetry/glean/private/EventMetricTypeTest.kt

@@ -258,14 +258,14 @@ class EventMetricTypeTest {
             ),
             allowedExtraKeys = listOf("test_name"),
         )
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
         eventMetric.record(EventMetricExtras(testName = "event1"))
         val snapshot1 = eventMetric.testGetValue()!!
         assertEquals(1, snapshot1.size)
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         eventMetric.record(EventMetricExtras(testName = "event2"))
         assertNull(eventMetric.testGetValue())
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
         eventMetric.record(EventMetricExtras(testName = "event3"))
         val snapshot3 = eventMetric.testGetValue()!!
         assertEquals(1, snapshot3.size)
@@ -455,10 +455,10 @@ class EventMetricTypeTest {
     }
 
     @Test
-    fun `overdue events are discarded if ping is not registered`() {
+    fun `events are discarded if ping is not registered`() {
         // This is similar to the above test,
         // except that we register the custom ping AFTER initialize.
-        // Overdue events are thus discarded because the ping is unknown at initialization time.
+        // Events are thus discarded upon `record` because the ping is unknown.
 
         val server = getMockWebServer()
         val context = getContext()
@@ -484,9 +484,9 @@ class EventMetricTypeTest {
             allowedExtraKeys = listOf("some_extra"),
         )
 
-        // Let's record a single event. This will be queued up but not be sent.
+        // Let's record a single event. This will NOT be queued up because the ping is not registered.
         event.record(TestEventExtras(someExtra = "alternative"))
-        assertEquals(1, event.testGetValue()!!.size)
+        assertNull(event.testGetValue())
 
         // Let's act as if the app was stopped
         Glean.testDestroyGleanHandle()
@@ -511,6 +511,7 @@ class EventMetricTypeTest {
             enabled = true,
             schedulesPings = emptyList(),
             reasonCodes = listOf(),
+            followsCollectionEnabled = true,
         )
 
         // Trigger worker task to upload the pings in the background.

glean-core/android/src/test/java/mozilla/telemetry/glean/private/ObjectMetricTypeTest.kt

@@ -163,7 +163,7 @@ class ObjectMetricTypeTest {
             ),
         )
 
-        Glean.setUploadEnabled(true)
+        Glean.setCollectionEnabled(true)
 
         var balloons = BalloonsObject()
         balloons.add(BalloonsObjectItem(colour = "yellow", diameter = 10))
@@ -177,7 +177,7 @@ class ObjectMetricTypeTest {
         var expected: JsonElement = Json.decodeFromString(expectedJson)
         assertEquals(expected, metric.testGetValue()!!)
 
-        Glean.setUploadEnabled(false)
+        Glean.setCollectionEnabled(false)
         balloons = BalloonsObject()
         balloons.add(BalloonsObjectItem(colour = "blue", diameter = 1))
         metric.set(balloons)