Merge pull request #1603 from mozilla/new-event-extras

.flake8

@@ -1,2 +1,3 @@
 [flake8]
 max-line-length = 100
+exclude = glean-core/python/glean/_glean_ffi.py

.gitignore

@@ -51,7 +51,7 @@ dist/
 /samples/csharp/.venv/
 
 # local stuff
-data/
+/data/
 glean-core/data
 glean_app*
 !glean_app.c
@@ -62,6 +62,7 @@ samples/ios/app/.venv/
 htmlcov/
 *.log
 
+glean-core/python/glean/_glean_ffi.py
 __pycache__
 *.py[cod]
 .Python

CHANGELOG.md

@@ -2,6 +2,42 @@
 
 [Full changelog](https://github.com/mozilla/glean/compare/v38.0.1...main)
 
+* General
+  * Add new event extras API to all implementations. See below for details ([#1603](https://github.com/mozilla/glean/pull/1603))
+* Rust
+  * **Breaking Change**: Allow event extras to be passed as an object.
+    This replaces the old `HashMap`-based API.
+    Values default to `string`.
+    See [the event documentation](https://mozilla.github.io/glean/book/reference/metrics/event.html#recordobject) for details.
+    ([#1603](https://github.com/mozilla/glean/pull/1603))
+    Old code:
+
+    ```
+    let mut extra = HashMap::new();
+    extra.insert(SomeExtra::Key1, "1".into());
+    extra.insert(SomeExtra::Key2, "2".into());
+    metric.record(extra);
+    ```
+
+    New code:
+
+    ```
+    let extra = SomeExtra {
+        key1: Some("1".into()),
+        key2: Some("2".into()),
+    };
+    metric.record(extra);
+    ```
+* Android
+  * **Deprecation**: The old event recording API is replaced by a new one, accepting a typed object ([#1603](https://github.com/mozilla/glean/pull/1603)).
+    See [the event documentation](https://mozilla.github.io/glean/book/reference/metrics/event.html#recordobject) for details.
+* Python
+  * **Deprecation**: The old event recording API is replaced by a new one, accepting a typed object ([#1603](https://github.com/mozilla/glean/pull/1603)).
+    See [the event documentation](https://mozilla.github.io/glean/book/reference/metrics/event.html#recordobject) for details.
+* Swift
+  * **Deprecation**: The old event recording API is replaced by a new one, accepting a typed object ([#1603](https://github.com/mozilla/glean/pull/1603)).
+    See [the event documentation](https://mozilla.github.io/glean/book/reference/metrics/event.html#recordobject) for details.
+
 # v38.0.1 (2021-05-17)
 
 [Full changelog](https://github.com/mozilla/glean/compare/v38.0.0...v38.0.1)

Makefile

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

docs/user/reference/metrics/event.md

@@ -18,57 +18,50 @@ Each event contains the following data:
 
 ## Recording API
 
-### `record`
+### `record(object)`
 
-Record a new event, with optional extra values.
+_Added in: [v38.0.0](../../appendix/changelog.md)_
+<!-- FIXME: Update anchor when v38.0.0 is actually released -->
+
+Record a new event, with optional typed extra values.
+This requires `type` annotations in the definition.
+See [Extra metrics parameters](#extra-metric-parameters).
 
 {{#include ../../../shared/tab_header.md}}
 
 <div data-lang="Kotlin" class="tab">
 
-Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Keys` added.
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Extra` added.
 
 ```Kotlin
 import org.mozilla.yourApplication.GleanMetrics.Views
 
-Views.loginOpened.record(mapOf(Views.loginOpenedKeys.sourceOfLogin to "toolbar"))
+Views.loginOpened.record(Views.loginOpenedExtra(sourceOfLogin = "toolbar"))
 ```
 
 </div>
 
-<div data-lang="Java" class="tab">
-
-```Java
-import org.mozilla.yourApplication.GleanMetrics.Views;
-
-Views.INSTANCE.loginOpened.record();
-```
-
-</div>
+<div data-lang="Java" class="tab"></div>
 
 <div data-lang="Swift" class="tab">
 
-Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Keys` added.
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Extra` added.
 
 ```Swift
-Views.loginOpened.record(extra: [.sourceOfLogin: "toolbar"])
+Views.loginOpened.record(LoginOpenedExtra(sourceOfLogin: "toolbar"))
 ```
 
 </div>
 
 <div data-lang="Python" class="tab">
 
-Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `_keys` added.
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `_extra` added.
 
 ```Python
 from glean import load_metrics
 metrics = load_metrics("metrics.yaml")
 
-metrics.views.login_opened.record(
-    {
-        metrics.views.login_opened_keys.SOURCE_OF_LOGIN: "toolbar"
-    }
-)
+metrics.views.login_opened.record(LoginOpenedExtra(sourceOfLogin="toolbar"))
 ```
 
 </div>
@@ -78,10 +71,9 @@ metrics.views.login_opened.record(
 Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Keys` added.
 
 ```Rust
-use metrics::views;
+use metrics::views::{self, LoginOpenedExtra};
 
-let mut extra = HashMap::new();
-extra.insert(views::LoginOpenedKeys::SourceOfLogin, "toolbar".into());
+let extra = LoginOpenedExtra { source_of_login: Some("toolbar".to_string()) };
 views::login_opened.record(extra);
 ```
 
@@ -104,11 +96,8 @@ views.loginOpened.record({ sourceOfLogin: "toolbar" });
 ```c++
 #include "mozilla/glean/GleanMetrics.h"
 
-using mozilla::glean::views::LoginOpenedKeys;
-nsTArray<Tuple<LoginOpenedKeys, nsCString>> extra;
-nsCString source = "toolbar"_ns;
-extra.AppendElement(MakeTuple(LoginOpenedKeys::SourceOfLogin, source));
-
+using mozilla::glean::views::LoginOpenedExtra;
+LoginOpenedExtra extra = { .source_of_login = Some("value"_ns) };
 mozilla::glean::views::login_opened.Record(std::move(extra))
 ```
 
@@ -121,6 +110,89 @@ Glean.views.loginOpened.record(extra);
 
 </div>
 
+{{#include ../../../shared/tab_footer.md}}
+
+### `record(map)` (_deprecated_)
+
+_Deprecated in: [v38.0.0](../../appendix/changelog.md)_
+<!-- FIXME: Update anchor when v38.0.0 is actually released -->
+
+Record a new event, with optional extra values.
+
+{{#include ../../../shared/blockquote-info.html}}
+
+##### Deprecation notice
+
+> This API is used in v38.0.0 if an event has no `type` annotations in the definition.
+> See [Extra metrics parameters](#extra-metric-parameters).
+>
+> In future versions extra values will default to a `string` type and this API will be removed.  
+> In Rust and Firefox Desktop this API is not supported.
+
+{{#include ../../../shared/tab_header.md}}
+
+<div data-lang="Kotlin" class="tab">
+
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Keys` added.
+
+```Kotlin
+import org.mozilla.yourApplication.GleanMetrics.Views
+
+Views.loginOpened.record(mapOf(Views.loginOpenedKeys.sourceOfLogin to "toolbar"))
+```
+
+</div>
+
+<div data-lang="Java" class="tab">
+
+```Java
+import org.mozilla.yourApplication.GleanMetrics.Views;
+
+Views.INSTANCE.loginOpened.record();
+```
+
+</div>
+
+<div data-lang="Swift" class="tab">
+
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `Keys` added.
+
+```Swift
+Views.loginOpened.record(extra: [.sourceOfLogin: "toolbar"])
+```
+
+</div>
+
+<div data-lang="Python" class="tab">
+
+Note that an `enum` has been generated for handling the `extra_keys`: it has the same name as the event metric, with `_keys` added.
+
+```Python
+from glean import load_metrics
+metrics = load_metrics("metrics.yaml")
+
+metrics.views.login_opened.record(
+    {
+        metrics.views.login_opened_keys.SOURCE_OF_LOGIN: "toolbar"
+    }
+)
+```
+
+</div>
+
+<div data-lang="Rust" class="tab"></div>
+
+<div data-lang="JavaScript" class="tab">
+
+```js
+import * as views from "./path/to/generated/files/views.js";
+
+views.loginOpened.record({ sourceOfLogin: "toolbar" });
+```
+
+</div>
+
+<div data-lang="Firefox Desktop" class="tab"></div>
 
 {{#include ../../../shared/tab_footer.md}}
 
@@ -383,6 +455,7 @@ views:
     extra_keys:
       source_of_login:
         description: The source from which the login view was opened, e.g. "toolbar".
+        type: string
 ```
 
 For a full reference on metrics parameters common to all metric types,
@@ -398,6 +471,8 @@ A maximum of 10 extra keys is allowed.
 Each extra key contains additional metadata:
 
 - `description`: **Required.** A description of the key.
+* `type`: The type of value this extra key can hold. One of `string`, `boolean`, `quantity`. Defaults to `string`.
+  **Note**: If not specified only the legacy API on `record` is available.
 
 ## Data questions
 

docs/user/user/collected-metrics/metrics.md

@@ -168,5 +168,5 @@ In addition to those built-in metrics, the following metrics are added to the pi
 
 Data categories are [defined here](https://wiki.mozilla.org/Firefox/Data_Collection).
 
-<!-- AUTOGENERATED BY glean_parser.  DO NOT EDIT. DO NOT COMMIT. -->
+<!-- AUTOGENERATED BY glean_parser. DO NOT EDIT. -->
 

glean-core/Cargo.toml

@@ -18,7 +18,7 @@ include = [
 ]
 
 [package.metadata.glean]
-glean-parser = "3.2.0"
+glean-parser = "3.4.0"
 
 [badges]
 circle-ci = { repository = "mozilla/glean", branch = "main" }