зеркало из https://github.com/mozilla/glean.git
Conform UUID metric reference page to new format
[doc only]
This commit is contained in:
brizental
Родитель
c3f3153d2e
Коммит
824d056d96
|
|
@ -1,24 +1,12 @@
|
|||
# UUID
|
||||
|
||||
UUIDs are used to record values that uniquely identify some entity, such as a client id.
|
||||
UUIDs metrics are used to record values that uniquely identify some entity, such as a client id.
|
||||
|
||||
## Configuration
|
||||
## Recording API
|
||||
|
||||
You first need to add an entry for it to the `metrics.yaml` file:
|
||||
### `generateAndSet`
|
||||
|
||||
```YAML
|
||||
user:
|
||||
client_id:
|
||||
type: uuid
|
||||
description: >
|
||||
A unique identifier for the client's profile
|
||||
lifetime: user
|
||||
...
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
Now that the UUID is defined in `metrics.yaml`, you can use the metric to record values in the application's code.
|
||||
Sets a UUID metric to a generated [UUID](https://datatracker.ietf.org/doc/html/rfc4122) value.
|
||||
|
||||
{{#include ../../../shared/tab_header.md}}
|
||||
|
||||
|
|
@ -27,19 +15,8 @@ Now that the UUID is defined in `metrics.yaml`, you can use the metric to record
|
|||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
User.clientId.generateAndSet() // Generate a new UUID and record it
|
||||
User.clientId.set(UUID.randomUUID()) // Set a UUID explicitly
|
||||
```
|
||||
|
||||
There are test APIs available too.
|
||||
|
||||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
// Was anything recorded?
|
||||
assertTrue(User.clientId.testHasValue())
|
||||
// Was it the expected value?
|
||||
assertEquals(uuid, User.clientId.testGetValue())
|
||||
// Generate a new UUID and record it
|
||||
User.clientId.generateAndSet()
|
||||
```
|
||||
|
||||
</div>
|
||||
|
|
@ -49,19 +26,8 @@ assertEquals(uuid, User.clientId.testGetValue())
|
|||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
User.INSTANCE.clientId.generateAndSet(); // Generate a new UUID and record it
|
||||
User.INSTANCE.clientId.set(UUID.randomUUID()); // Set a UUID explicitly
|
||||
```
|
||||
|
||||
There are test APIs available too:
|
||||
|
||||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
// Was anything recorded?
|
||||
assertTrue(User.INSTANCE.clientId.testHasValue());
|
||||
// Was it the expected value?
|
||||
assertEquals(uuid, User.INSTANCE.clientId.testGetValue());
|
||||
// Generate a new UUID and record it
|
||||
User.INSTANCE.clientId.generateAndSet();
|
||||
```
|
||||
|
||||
</div>
|
||||
|
|
@ -70,19 +36,8 @@ assertEquals(uuid, User.INSTANCE.clientId.testGetValue());
|
|||
<div data-lang="Swift" class="tab">
|
||||
|
||||
```Swift
|
||||
User.clientId.generateAndSet() // Generate a new UUID and record it
|
||||
User.clientId.set(UUID()) // Set a UUID explicitly
|
||||
```
|
||||
|
||||
There are test APIs available too.
|
||||
|
||||
```Swift
|
||||
@testable import Glean
|
||||
|
||||
// Was anything recorded?
|
||||
XCTAssert(User.clientId.testHasValue())
|
||||
// Was it the expected value?
|
||||
XCTAssertEqual(uuid, try User.clientId.testGetValue())
|
||||
// Generate a new UUID and record it
|
||||
User.clientId.generateAndSet()
|
||||
```
|
||||
|
||||
</div>
|
||||
|
|
@ -90,46 +45,11 @@ XCTAssertEqual(uuid, try User.clientId.testGetValue())
|
|||
<div data-lang="Python" class="tab">
|
||||
|
||||
```Python
|
||||
import uuid
|
||||
|
||||
from glean import load_metrics
|
||||
metrics = load_metrics("metrics.yaml")
|
||||
|
||||
# Generate a new UUID and record it
|
||||
metrics.user.client_id.generate_and_set()
|
||||
# Set a UUID explicitly
|
||||
metrics.user.client_id.set(uuid.uuid4())
|
||||
```
|
||||
|
||||
There are test APIs available too.
|
||||
|
||||
```Python
|
||||
# Was anything recorded?
|
||||
assert metrics.user.client_id.test_has_value()
|
||||
# Was it the expected value?
|
||||
assert uuid == metrics.user.client_id.test_get_value()
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="C#" class="tab">
|
||||
|
||||
```C#
|
||||
using static Mozilla.YourApplication.GleanMetrics.User;
|
||||
|
||||
User.clientId.GenerateAndSet(); // Generate a new UUID and record it
|
||||
User.clientId.Set(System.Guid.NewGuid()); // Set a UUID explicitly
|
||||
```
|
||||
|
||||
There are test APIs available too:
|
||||
|
||||
```C#
|
||||
using static Mozilla.YourApplication.GleanMetrics.User;
|
||||
|
||||
// Was anything recorded?
|
||||
Assert.True(User.clientId.TestHasValue());
|
||||
// Was it the expected value?
|
||||
Assert.Equal(uuid, User.clientId.TestGetValue());
|
||||
```
|
||||
|
||||
</div>
|
||||
|
|
@ -140,92 +60,415 @@ Assert.Equal(uuid, User.clientId.TestGetValue());
|
|||
use glean_metrics;
|
||||
use uuid::Uuid;
|
||||
|
||||
user::client_id.generate_and_set(); // Generate a new UUID and record it
|
||||
user::client_id.set(Uuid::new_v4()); // Set a UUID explicitly
|
||||
// Generate a new UUID and record it
|
||||
user::client_id.generate_and_set();
|
||||
```
|
||||
|
||||
There are test APIs available too:
|
||||
|
||||
```rust
|
||||
use glean_metrics;
|
||||
|
||||
let u = Uuid::new_v4();
|
||||
user::client_id.set(u);
|
||||
// Was anything recorded?
|
||||
assert!(user::client_id.test_get_value(None).is_some());
|
||||
// Does it have the expected value?
|
||||
assert_eq!(u, user::client_id.test_get_value(None).unwrap());
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="C++" class="tab">
|
||||
<div data-lang="Javascript" class="tab">
|
||||
|
||||
> **Note**: C++ APIs are only available in Firefox Desktop.
|
||||
```js
|
||||
import * as user from "./path/to/generated/files/user.js";
|
||||
|
||||
user.clientId.generateAndSet();
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Firefox Desktop" class="tab">
|
||||
|
||||
**C++**
|
||||
|
||||
```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/).
|
||||
**Javascript**
|
||||
|
||||
```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 ../../../shared/tab_footer.md}}
|
||||
|
||||
## Limits
|
||||
|
||||
* None.
|
||||
### `set`
|
||||
|
||||
## Examples
|
||||
Sets a UUID metric to a specific value.
|
||||
|
||||
{{#include ../../../shared/tab_header.md}}
|
||||
|
||||
<div data-lang="Kotlin" class="tab">
|
||||
|
||||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
// Set a UUID explicitly
|
||||
User.clientId.set(UUID.randomUUID()) // Set a UUID explicitly
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Java" class="tab">
|
||||
|
||||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
// Set a UUID explicitly
|
||||
User.INSTANCE.clientId.set(UUID.randomUUID());
|
||||
```
|
||||
</div>
|
||||
|
||||
|
||||
<div data-lang="Swift" class="tab">
|
||||
|
||||
```Swift
|
||||
User.clientId.set(UUID()) // Set a UUID explicitly
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Python" class="tab">
|
||||
|
||||
```Python
|
||||
import uuid
|
||||
|
||||
from glean import load_metrics
|
||||
metrics = load_metrics("metrics.yaml")
|
||||
|
||||
# Set a UUID explicitly
|
||||
metrics.user.client_id.set(uuid.uuid4())
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Rust" class="tab">
|
||||
|
||||
```rust
|
||||
use glean_metrics;
|
||||
use uuid::Uuid;
|
||||
|
||||
// Set a UUID explicitly
|
||||
user::client_id.set(Uuid::new_v4());
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Javascript" class="tab">
|
||||
|
||||
```js
|
||||
import * as user from "./path/to/generated/files/user.js";
|
||||
|
||||
const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
|
||||
user.clientId.set(uuid);
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Firefox Desktop" class="tab">
|
||||
|
||||
**C++**
|
||||
|
||||
```c++
|
||||
#include "mozilla/glean/GleanMetrics.h"
|
||||
|
||||
// Set a specific value.
|
||||
nsCString kUuid("decafdec-afde-cafd-ecaf-decafdecafde");
|
||||
mozilla::glean::user::client_id.Set(kUuid);
|
||||
```
|
||||
|
||||
**Javascript**
|
||||
|
||||
```js
|
||||
// Set a specific value.
|
||||
const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
|
||||
Glean.user.clientId.set(uuid);
|
||||
```
|
||||
</div>
|
||||
|
||||
{{#include ../../../shared/tab_footer.md}}
|
||||
|
||||
#### Recorded errors
|
||||
|
||||
* [`invalid_value`](../../user/metrics/error-reporting.md): if the value is set to a string that is not a UUID (only applies for dynamically-typed languages, such as Python).
|
||||
|
||||
|
||||
## Testing API
|
||||
|
||||
### `testGetValue`
|
||||
|
||||
Gets the recorded value for a given UUID metric.
|
||||
|
||||
{{#include ../../../shared/tab_header.md}}
|
||||
|
||||
<div data-lang="Kotlin" class="tab">
|
||||
|
||||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
// Was it the expected value?
|
||||
assertEquals(uuid, User.clientId.testGetValue())
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Java" class="tab">
|
||||
|
||||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
// Was it the expected value?
|
||||
assertEquals(uuid, User.INSTANCE.clientId.testGetValue());
|
||||
```
|
||||
</div>
|
||||
|
||||
|
||||
<div data-lang="Swift" class="tab">
|
||||
|
||||
```Swift
|
||||
@testable import Glean
|
||||
|
||||
// Was it the expected value?
|
||||
XCTAssertEqual(uuid, try User.clientId.testGetValue())
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Python" class="tab">
|
||||
|
||||
```Python
|
||||
from glean import load_metrics
|
||||
metrics = load_metrics("metrics.yaml")
|
||||
|
||||
# Was it the expected value?
|
||||
assert uuid == metrics.user.client_id.test_get_value()
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Rust" class="tab">
|
||||
|
||||
```rust
|
||||
use glean_metrics;
|
||||
use uuid::Uuid;
|
||||
|
||||
let u = Uuid::new_v4();
|
||||
// Does it have the expected value?
|
||||
assert_eq!(u, user::client_id.test_get_value(None).unwrap());
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Javascript" class="tab">
|
||||
|
||||
```js
|
||||
import * as user from "./path/to/generated/files/user.js";
|
||||
|
||||
const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
|
||||
assert(uuid, await user.clientId.testGetValue());
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Firefox Desktop" class="tab">
|
||||
|
||||
**C++**
|
||||
|
||||
```c++
|
||||
#include "mozilla/glean/GleanMetrics.h"
|
||||
|
||||
// Does it have an expected values?
|
||||
ASSERT_STREQ(kUuid.get(), mozilla::glean::user::client_id.TestGetValue().value().get());
|
||||
```
|
||||
|
||||
**Javascript**
|
||||
|
||||
```js
|
||||
const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
|
||||
Assert.equal(Glean.user.clientId.testGetValue(), uuid);
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
{{#include ../../../shared/tab_footer.md}}
|
||||
|
||||
### `testHasValue`
|
||||
|
||||
Whether or not **any** value was recorded for a given UUID metric.
|
||||
|
||||
{{#include ../../../shared/tab_header.md}}
|
||||
|
||||
<div data-lang="Kotlin" class="tab">
|
||||
|
||||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
// Was anything recorded?
|
||||
assertTrue(User.clientId.testHasValue())
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Java" class="tab">
|
||||
|
||||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
// Was anything recorded?
|
||||
assertTrue(User.INSTANCE.clientId.testHasValue());
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<div data-lang="Swift" class="tab">
|
||||
|
||||
```Swift
|
||||
@testable import Glean
|
||||
|
||||
// Was anything recorded?
|
||||
XCTAssert(User.clientId.testHasValue())
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Python" class="tab">
|
||||
|
||||
```Python
|
||||
from glean import load_metrics
|
||||
metrics = load_metrics("metrics.yaml")
|
||||
|
||||
# Was anything recorded?
|
||||
assert metrics.user.client_id.test_has_value()
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Rust" class="tab"></div>
|
||||
|
||||
<div data-lang="Javascript" class="tab"></div>
|
||||
|
||||
<div data-lang="Firefox Desktop" class="tab"></div>
|
||||
|
||||
{{#include ../../../shared/tab_footer.md}}
|
||||
|
||||
### `testGetNumRecordedErrors`
|
||||
|
||||
Gets number of errors recorded for a given UUID metric.
|
||||
|
||||
{{#include ../../../shared/tab_header.md}}
|
||||
|
||||
<div data-lang="Kotlin" class="tab">
|
||||
|
||||
```Kotlin
|
||||
import org.mozilla.yourApplication.GleanMetrics.User
|
||||
|
||||
assertEquals(
|
||||
1, User.clientId.testGetNumRecordedErrors(ErrorType.InvalidValue)
|
||||
)
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Java" class="tab">
|
||||
|
||||
```Java
|
||||
import org.mozilla.yourApplication.GleanMetrics.User;
|
||||
|
||||
assertEquals(
|
||||
1, User.INSTANCE.clientId.testGetNumRecordedErrors(ErrorType.InvalidValue)
|
||||
);
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
<div data-lang="Swift" class="tab">
|
||||
|
||||
```Swift
|
||||
XCTAssertEqual(1, User.clientId.testGetNumRecordedErrors(.invalidValue))
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Python" class="tab">
|
||||
|
||||
```Python
|
||||
from glean import load_metrics
|
||||
metrics = load_metrics("metrics.yaml")
|
||||
|
||||
from glean.testing import ErrorType
|
||||
|
||||
assert 1 == metrics.user.client_id.test_get_num_recorded_errors(
|
||||
ErrorType.INVALID_VALUE
|
||||
)
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Rust" class="tab">
|
||||
|
||||
```rust
|
||||
use glean::ErrorType;
|
||||
|
||||
use glean_metrics;
|
||||
|
||||
assert_eq!(
|
||||
1,
|
||||
user::client_id.test_get_num_recorded_errors(
|
||||
ErrorType::InvalidValue
|
||||
)
|
||||
);
|
||||
```
|
||||
|
||||
</div>
|
||||
|
||||
<div data-lang="Javascript" class="tab">
|
||||
|
||||
```js
|
||||
import * as user from "./path/to/generated/files/user.js";
|
||||
|
||||
// Was the string truncated, and an error reported?
|
||||
assert.strictEqual(1, await user.clientId.testGetNumRecordedErrors("invalid_value"));
|
||||
```
|
||||
</div>
|
||||
|
||||
<div data-lang="Firefox Desktop" class="tab" data-bug="1683171"></div>
|
||||
|
||||
{{#include ../../../shared/tab_footer.md}}
|
||||
|
||||
## Metric Parameters
|
||||
|
||||
You first need to add an entry for it to the `metrics.yaml` file:
|
||||
|
||||
```YAML
|
||||
user:
|
||||
client_id:
|
||||
type: uuid
|
||||
description: >
|
||||
A unique identifier for the client's profile
|
||||
bugs:
|
||||
- https://bugzilla.mozilla.org/000000
|
||||
data_reviews:
|
||||
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
|
||||
notification_emails:
|
||||
- me@mozilla.com
|
||||
expires: 2020-10-01
|
||||
```
|
||||
|
||||
For a full reference on metrics parameters common to all metric types,
|
||||
refer to the metrics [YAML format](../yaml/index.md) reference page.
|
||||
|
||||
### Extra metric parameters
|
||||
|
||||
N/A
|
||||
|
||||
## Data questions
|
||||
|
||||
* A unique identifier for the client.
|
||||
|
||||
## Recorded errors
|
||||
|
||||
* `invalid_value`: if the value is set to a string that is not a UUID (only applies for dynamically-typed languages, such as Python).
|
||||
|
||||
## Reference
|
||||
|
||||
* [Kotlin API docs](../../../javadoc/glean/mozilla.telemetry.glean.private/-uuid-metric-type/index.html).
|
||||
* [Swift API docs](../../../swift/Classes/UuidMetricType.html)
|
||||
* [Python API docs](../../../python/glean/metrics/uuid.html)
|
||||
* [Rust API docs](../../../docs/glean/private/uuid/struct.UuidMetric.html)
|
||||
* [Javascript API docs](https://mozilla.github.io/glean.js/classes/core_metrics_types_uuid.default.html#set)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче