Bug 1933679 - Docs for collection-enabled mode

.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.0.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.0
 	$(GLEAN_PYENV)/bin/glean_parser translate --allow-reserved \
 		 -f markdown \
 		 -o ./docs/user/user/collected-metrics \

bin/build-rust-docs.sh

@@ -49,6 +49,7 @@ echo '<meta http-equiv=refresh content=0;url=./adding-glean-to-your-project/inde
 # General API
 echo '<meta http-equiv=refresh content=0;url=../reference/general/index.html>' > build/docs/book/user/general-api.html
 echo '<meta http-equiv=refresh content=0;url=../reference/general/experiments-api.html>' > build/docs/book/user/experiments-api.html
+echo '<meta http-equiv=refresh content=0;url=toggling-collection-status.html>' > build/docs/book/user/reference/general/toggling-upload-status.html
 # Metrics API
 mkdir -p build/docs/book/user/metrics/
 echo '<meta http-equiv=refresh content=0;url=../../reference/metrics/boolean.html>' > build/docs/book/user/metrics/boolean.html

docs/user/SUMMARY.md

@@ -57,7 +57,7 @@
     - [Tags](reference/yaml/tags.md)
 - [General API](reference/general/index.md)
     - [Initializing](reference/general/initializing.md)
-    - [Toggling upload status](reference/general/toggling-upload-status.md)
+    - [Toggling collection status](reference/general/toggling-collection-status.md)
     - [Annotating experiments](reference/general/experiments-api.md)
     - [Registering custom pings](reference/general/register-custom-pings.md)
     - [Shut down](reference/general/shutdown.md)

docs/user/reference/general/index.md

@@ -20,7 +20,7 @@ The Glean SDKs provide a general API that supports the following operations. See
 | Operation | Description | Notes |
 | --------- | ----------- | ----- |
 | `initialize` | Configure and initialize the Glean SDK. | [Initializing the Glean SDK](./initializing.md) |
-| `setUploadEnabled` | Enable or disable Glean collection and upload. | [Toggling upload status](./toggling-upload-status.md) |
+| `setCollectionEnabled` | Enable or disable Glean collection and upload. | [Toggling collection status](./toggling-collection-status.md) |
 | `registerPings` | Register custom pings generated from `pings.yaml`. | [Custom pings][custom-pings] |
 | `setExperimentActive` | Indicate that an experiment is running. | [Using the Experiments API][experiments-api] |
 | `setExperimentInactive` | Indicate that an experiment is no longer running.. | [Using the Experiments API][experiments-api] |

docs/user/reference/general/initializing.md

@@ -86,7 +86,7 @@ To learn about SDK specific configuration options available, refer to the [Refer
 >
 > Always pass the user preference, e.g. `Glean.initialize(uploadEnabled=userSettings.telemetryEnabled)` or the equivalent for your application.
 >
-> Calling `Glean.setUploadEnabled(false)` at a later point will trigger [`deletion-request` pings](../../user/pings/deletion-request.md) and regenerate client IDs.
+> Calling `Glean.setCollectionEnabled(false)` at a later point will trigger [`deletion-request` pings](../../user/pings/deletion-request.md) and regenerate client IDs.
 > This should only be done if the user preference actually changes.
 
 {{#include ../../../shared/tab_header.md}}

docs/user/reference/general/toggling-upload-status.md → docs/user/reference/general/toggling-collection-status.md

@@ -1,39 +1,49 @@
-# Toggling upload status
+# Toggling collection status
 
-The Glean SDKs provide an API for toggling Glean's upload status after initialization.
+The Glean SDKs provide an API for toggling Glean's collection status after initialization.
 
 Applications instrumented with Glean
 [are expected to](../../user/adding-glean-to-your-project/index.md#glean-integration-checklist)
-provide some form of user interface to allow for toggling the upload status.
+provide some form of user interface to allow for toggling the collection status.
 
-## Disabling upload
+{{#include ../../../shared/blockquote-info.html}}
 
-When upload is disabled, the Glean SDK will perform the following tasks:
+## `setUploadEnabled` is deprecated since Glean v63.0.0
+
+> Prior to Glean v63.0.0 this API was called `setUploadEnabled`.
+> `setUploadEnabled` is now deprecated and replaced by `setCollectionEnabled`.
+> It behaves the same way with respect to built-in pings and custom pings,
+> unless those are marked with `follows_collection_enabled: false`.
+> See [TODO: the collection-enabled documentation for details]().
+
+## Disabling collection
+
+When collection is disabled, the Glean SDK will perform the following tasks:
 
 1. Submit a [`deletion-request`](../../user/pings/deletion-request.md) ping.
 2. Cancel scheduled ping uploads.
 3. Clear metrics and pings data from the client, except for the
   [`first_run_date`](../../user/pings/index.html#the-client_info-section) metric.
 
-While upload is disabled, metrics aren't recorded and no data is uploaded.
+While collection is disabled, metrics aren't recorded and no data is uploaded.
 
-## Enabling upload
+## Enabling collection
 
-When upload is enabled, the Glean SDK will re-initialize its [core metrics](../../user/collected-metrics/metrics.md).
+When collection is enabled, the Glean SDK will re-initialize its [core metrics](../../user/collected-metrics/metrics.md).
 The only core metric that is not re-initialized is the [`first_run_date`](../../user/pings/index.html#the-client_info-section) metric.
 
-While upload is enabled all metrics are recorded as expected
+While collection is enabled all metrics are recorded as expected
 and pings are sent to the telemetry servers.
 
 ## API
 
-### `Glean.setUploadEnabled(boolean)`
+### `Glean.setCollectionEnabled(boolean)`
 
-Enables or disables upload.
+Enables or disables collection.
 
 If called prior to initialize this function is a no-op.
 
-If the upload state is not actually changed in between calls to this function, it is also a no-op.
+If the collection state is not actually changed in between calls to this function, it is also a no-op.
 
 {{#include ../../../shared/tab_header.md}}
 
@@ -48,9 +58,9 @@ open class MainActivity : AppCompatActivity() {
 
         uploadSwitch.setOnCheckedChangeListener { _, isChecked ->
             if (isChecked) {
-                Glean.setUploadEnabled(true)
+                Glean.setCollectionEnabled(true)
             } else {
-                Glean.setUploadEnabled(false)
+                Glean.setCollectionEnabled(false)
             }
         }
     }
@@ -63,7 +73,7 @@ open class MainActivity : AppCompatActivity() {
 ```Java
 import mozilla.telemetry.glean.Glean
 
-Glean.INSTANCE.setUploadEnabled(false);
+Glean.INSTANCE.setCollectionEnabled(false);
 ```
 
 </div>
@@ -80,7 +90,7 @@ class ViewController: UIViewController {
     // ...
 
     @IBAction func enableToggled(_: Any) {
-        Glean.shared.setUploadEnabled(enableSwitch.isOn)
+        Glean.shared.setCollectionEnabled(enableSwitch.isOn)
     }
 }
 ```
@@ -92,7 +102,7 @@ class ViewController: UIViewController {
 ```python
 from glean import Glean
 
-Glean.set_upload_enabled(false)
+Glean.set_collection_enabled(false)
 ```
 
 </div>
@@ -101,13 +111,12 @@ Glean.set_upload_enabled(false)
 ```Rust
 use glean;
 
-glean::set_upload_enabled(false);
+glean::set_collection_enabled(false);
 ```
 
 </div>
 <div data-lang="JavaScript" class="tab">
 
-
 ```js
 import Glean from "@mozilla/glean/web";
 
@@ -121,14 +130,20 @@ uploadSwitch.addEventListener("change", event => {
 });
 ```
 
+{{#include ../../../shared/blockquote-info.html}}
+
+## Glean.js still uses `setUploadEnabled`
+
+> Glean.js did not yet switch to the new naming and continues to use `setUploadEnabled` unchanged.
+
 </div>
 <div data-lang="Firefox Desktop" class="tab" data-info="On Firefox Desktop data collection is toggled internally."></div>
 
 {{#include ../../../shared/tab_footer.md}}
 
 ## Reference
 
-* [Swift API docs](../../../swift/Classes/Glean.html#/s:5GleanAAC16setUploadEnabledyySbF)
-* [Python API docs](../../../python/glean/index.html#glean.Glean.set_upload_enabled)
-* [Rust API docs](../../../docs/glean/fn.set_upload_enabled.html)
+* [Swift API docs](../../../swift/Classes/Glean.html#/s:5GleanAAC16setCollectionEnabledyySbF)
+* [Python API docs](../../../python/glean/index.html#glean.Glean.set_collection_enabled)
+* [Rust API docs](../../../docs/glean/fn.set_collection_enabled.html)
 * [JavaScript API docs](https://mozilla.github.io/glean.js/reference/uploaders/#uploadenabled)

docs/user/reference/pings/index.md

@@ -108,6 +108,84 @@ GleanPings.search.submit("performed");
 
 {{#include ../../../shared/tab_footer.md}}
 
+### `setEnabled`
+
+TODO
+
+{{#include ../../../shared/tab_header.md}}
+
+<div data-lang="Kotlin" class="tab">
+
+```kotlin
+import org.mozilla.yourApplication.GleanMetrics.Pings
+
+Pings.search.setEnabled(false)
+```
+
+</div>
+
+<div data-lang="Java" class="tab">
+
+```java
+import org.mozilla.yourApplication.GleanMetrics.Pings
+
+Pings.INSTANCE.search.setEnabled(false);
+```
+
+</div>
+
+<div data-lang="Swift" class="tab">
+
+```swift
+import Glean
+
+GleanMetrics.Pings.shared.search.setEnabled(false)
+```
+
+</div>
+
+<div data-lang="Python" class="tab">
+
+```Python
+from glean import load_pings
+
+pings = load_pings("pings.yaml")
+
+pings.search.set_enabled(False)
+```
+
+</div>
+
+<div data-lang="Rust" class="tab">
+
+```Rust
+use glean::Pings;
+
+pings::search.set_enabled(false);
+```
+
+</div>
+
+<div data-lang="JavaScript" class="tab"></div>
+
+<div data-lang="Firefox Desktop" class="tab">
+
+**C++**
+
+```cpp
+mozilla::glean_pings::Search.SetEnabled(false);
+```
+
+**JavaScript**
+
+```js
+GleanPings.search.setEnabled(false);
+```
+
+</div>
+
+{{#include ../../../shared/tab_footer.md}}
+
 ## Testing API
 
 ### `getRegisteredPingNames`

docs/user/user/adding-glean-to-your-project/index.md

@@ -26,7 +26,7 @@ Additionally, applications (but not libraries) **must**:
 
 6. [Initialize Glean](../../reference/general/initializing.md) as early as possible at application startup.
 
-7. Provide a way for users to turn data collection off (e.g. providing settings to control `Glean.setUploadEnabled()`). The exact method used is application-specific.
+7. Provide a way for users to turn data collection off (e.g. providing settings to control `Glean.setCollectionEnabled()`). The exact method used is application-specific.
 
 {{#include ../../../shared/blockquote-info.html}}
 

glean-core/Cargo.toml

@@ -21,7 +21,7 @@ include = [
 rust-version = "1.76"
 
 [package.metadata.glean]
-glean-parser = "15.2.0"
+glean-parser = "16.0.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)
+    }
 }