bug 1680020 - Add C++ and JS docs for existing and incoming metric types

2020-12-17 15:14:00 -05:00 · 2020-12-17 15:14:00 -05:00 · 4d152fea69
--- a/docs/user/metrics/boolean.md
+++ b/docs/user/metrics/boolean.md
@ -144,6 +144,43 @@ assert!(flags::a11y_enabled.test_get_value(None).unwrap());

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::flags::a11y_enabled.Set(false);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+ASSERT_EQ(false, mozilla::glean::flags::a11y_enabled.TestGetValue().value());
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are currently only available in Firefox Desktop.
+> General JavaScript support is coming soon via [the Glean.js project](https://github.com/mozilla/glean.js/).
+
+```js
+Glean.flags.a11yEnabled.set(false);
+```
+
+There are test APIs available too:
+
+```js
+Assert.equal(false, Glean.flags.a11yEnabled.testGetValue());
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/counter.md
+++ b/docs/user/metrics/counter.md
@ -181,6 +181,48 @@ assert_eq!(

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::controls::refresh_pressed.Add(1);
+mozilla::glean::controls::refresh_pressed.Add(5);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does the counter have the expected value?
+ASSERT_EQ(6, mozilla::glean::controls::refresh_pressed.TestGetValue().value());
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are currently only available in Firefox Desktop.
+> General JavaScript support is coming soon via [the Glean.js project](https://github.com/mozilla/glean.js/).
+
+```js
+Glean.controls.refreshPressed.add(1);
+Glean.controls.refreshPressed.add(5);
+```
+
+There are test APIs available too:
+
+```js
+Assert.equal(6, Glean.controls.refreshPressed.testGetValue());
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/datetime.md
+++ b/docs/user/metrics/datetime.md
@ -208,6 +208,52 @@ assert_eq!(0, install::first_run.test_get_num_recorded_errors(

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+PRExplodedTime date = {0, 35, 10, 12, 6, 10, 2020, 0, 0, {5 * 60 * 60, 0}};
+mozilla::glean::install::first_run.Set(&date);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have the expected value?
+ASSERT_STREQ(
+  mozilla::glean::install::first_run.TestGetValue().value(),
+  "2020-11-06T12:10:35+05:00"_ns
+);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+const value = new Date("2020-06-11T12:00:00");
+Glean.install.firstRun.set(value.getTime() * 1000);
+```
+
+There are test APIs available too:
+
+```js
+Assert.ok(Glean.install.firstRun.testGetValue().startsWith("2020-06-11T12:00:00"));
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/event.md
+++ b/docs/user/metrics/event.md
@ -180,6 +180,56 @@ assert_eq!(0, views::login_opened.test_get_num_recorded_errors(ErrorType::Invali

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```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));
+
+mozilla::glean::views::login_opened.Record(std::move(extra))
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have a value?
+ASSERT_TRUE(mozilla::glean::views::login_opened.TestGetValue().isSome());
+// Does it have the expected value?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1678567
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+let extra = { sourceOfLogin: "toolbar" };
+Glean.views.loginOpened.record(extra);
+```
+
+There are test APIs available too:
+
+```js
+// Does it have the expected value?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1678567
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/memory_distribution.md
+++ b/docs/user/metrics/memory_distribution.md
@ -208,6 +208,50 @@ assert_eq!(1, memory::heap_allocated.test_get_num_recorded_errors(InvalidValue))

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::memory::heap_allocated.Accumulate(bytes / 1024);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have the expected value?
+ASSERT_EQ(11 * 1024, mozilla::glean::memory::heap_allocated.TestGetValue().value().sum);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+Glean.memory.heapAllocated.accumulate(bytes / 1024);
+```
+
+There are test APIs available too:
+
+```js
+const data = Glean.memory.heapAllocated.testGetValue();
+Assert.equal(11 * 1024, data.sum);
+// Does it have the right number of samples?
+Assert.equal(1, Object.entries(data.values).reduce(([bucket, count], sum) => count + sum, 0));
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/string.md
+++ b/docs/user/metrics/string.md
@ -167,6 +167,51 @@ Assert.Equal(
 ```


+</div>
+
+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::search_default::name.Set("wikipedia"_ns);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have the expected value?
+ASSERT_STREQ(
+  "wikipedia",
+  mozilla::glean::search_default::name.TestGetValue().value().get()
+);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are currently only available in Firefox Desktop.
+> General JavaScript support is coming soon via [the Glean.js project](https://github.com/mozilla/glean.js/).
+
+```js
+Glean.searchDefault.name.set("wikipedia");
+```
+
+There are test APIs available too:
+
+```js
+Assert.equal("wikipedia", Glean.searchDefault.name.testGetValue());
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
 </div>

 {{#include ../../tab_footer.md}}
--- a/docs/user/metrics/string_list.md
+++ b/docs/user/metrics/string_list.md
@ -187,6 +187,53 @@ assert_eq!(

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::search::engines.Add("wikipedia"_ns);
+mozilla::glean::search::engines.Add("duck duck go"_ns);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have the expected values?
+nsTArray<nsCString> list = mozilla::glean::search::engines.TestGetValue();
+ASSERT_TRUE(list.Contains("wikipedia"_ns));
+ASSERT_TRUE(list.Constains("duck duck go"_ns));
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+Glean.search.engines.add("wikipedia");
+Glean.search.engines.add("duck duck go");
+```
+
+There are test APIs available too:
+
+```js
+const engines = Glean.search.engines.testGetValue();
+Assert.ok(engines.includes("wikipedia"));
+Assert.ok(engines.includes("duck duck go"));
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/timespan.md
+++ b/docs/user/metrics/timespan.md
@ -272,6 +272,51 @@ assert_eq!(1, login_time.test_get_num_recorded_errors(ErrorType::InvalidValue));

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+mozilla::glean::auth::login_time.Start();
+PR_Sleep(PR_MillisecondsToInterval(10));
+mozilla::glean::auth::login_time.Stop();
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have an expected values?
+ASSERT_TRUE(mozilla::glean::auth::login_time.TestGetValue().value() > 0);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+Glean.auth.loginTime.start();
+await sleep(10);
+Glean.auth.loginTime.stop();
+```
+
+There are test APIs available too:
+
+```js
+Assert.ok(Glean.auth.loginTime.testGetValue() > 0);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Raw API
--- a/docs/user/metrics/timing_distribution.md
+++ b/docs/user/metrics/timing_distribution.md
@ -266,7 +266,7 @@ Assert.Equal(0, Pages.pageLoad.TestGetNumRecordedErrors(ErrorType.InvalidValue))
 use glean_metrics;

 fn on_page_start() {
-    self.timer_id = Pages.page_load.start();
+    self.timer_id = pages::page_load.start();
 }

 fn on_page_loaded() {
@ -296,6 +296,52 @@ for error in errors {

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+auto timerId = mozilla::glean::pages::page_load.Start();
+PR_Sleep(PR_MillisecondsToInterval(10));
+mozilla::glean::pages::page_load.StopAndAccumulate(timerId);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have an expected values?
+const data = mozilla::glean::pages::page_load.TestGetValue().value();
+ASSERT_TRUE(data.sum > 0);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are only available in Firefox Desktop.
+
+```js
+const timerId = Glean.pages.pageLoad.start();
+await sleep(10);
+Glean.pages.pageLoad.stopAndAccumulate(timerId);
+```
+
+There are test APIs available too:
+
+```js
+Assert.ok(Glean.pages.pageLoad.testGetValue().sum > 0);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits
--- a/docs/user/metrics/uuid.md
+++ b/docs/user/metrics/uuid.md
@ -159,6 +159,56 @@ assert_eq!(u, user::client_id.test_get_value(None).unwrap());

 </div>

+<div data-lang="C++" class="tab">
+
+> **Note**: C++ APIs are only available in Firefox Desktop.
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Generate a new UUID and record it.
+mozilla::glean::user::client_id.GenerateAndSet();
+// Set a specific value.
+nsCString kUuid("decafdec-afde-cafd-ecaf-decafdecafde");
+mozilla::glean::user::client_id.Set(kUuid);
+```
+
+There are test APIs available too:
+
+```c++
+#include "mozilla/glean/GleanMetrics.h"
+
+// Does it have an expected values?
+ASSERT_STREQ(kUuid.get(), mozilla::glean::user::client_id.TestGetValue().value().get());
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
+<div data-lang="JS" class="tab">
+
+> **Note**: JS APIs are currently only available in Firefox Desktop.
+> General JavaScript support is coming soon via [the Glean.js project](https://github.com/mozilla/glean.js/).
+
+```js
+// Generate a new UUID and record it.
+Glean.user.clientId.generateAndSet();
+// Set a specific value.
+const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
+Glean.user.clientId.set(uuid);
+```
+
+There are test APIs available too:
+
+```js
+Assert.equal(Glean.user.clientId.testGetValue(), uuid);
+// Did it run across any errors?
+// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
+```
+
+</div>
+
 {{#include ../../tab_footer.md}}

 ## Limits