Skip to content

Commit af41bac

Browse files
author
Beatriz Rizental
authored
Merge pull request #1715 from brizental/1719315-url
Bug 1719315 - Add documentation about the URL metric type
2 parents 6f89562 + 29d3138 commit af41bac

File tree

5 files changed

+186
-1
lines changed

5 files changed

+186
-1
lines changed

‎.dictionary‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
personal_ws-1.1 en 237 utf-8
1+
personal_ws-1.1 en 238 utf-8
22
AAR
33
AARs
44
ABI
@@ -226,6 +226,7 @@ tooltips
226226
transpiler
227227
travis
228228
und
229+
unencoded
229230
unhandled
230231
uniffi
231232
uploader

‎docs/dev/core/internal/payload.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,16 @@ A [UUID](../../../book/reference/metrics/uuid.md) is represented by the string r
150150
"29711dc8-a954-11e9-898a-eb4ea7e8fd3f"
151151
```
152152

153+
### URL
154+
155+
A [URL](../../../book/reference/metrics/url.md) is represented by the encoded string representation of the URL.
156+
157+
#### Example
158+
159+
```json
160+
"https://mysearchengine.com/?query=%25s"
161+
```
162+
153163
### Datetime
154164

155165
A [Datetime](../../../book/reference/metrics/datetime.md) is represented by its ISO8601 string representation, truncated to the metric's time unit.

‎docs/user/SUMMARY.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@
5454
- [Timing Distribution](reference/metrics/timing_distribution.md)
5555
- [Memory Distribution](reference/metrics/memory_distribution.md)
5656
- [UUID](reference/metrics/uuid.md)
57+
- [URL](reference/metrics/url.md)
5758
- [Datetime](reference/metrics/datetime.md)
5859
- [Event](reference/metrics/event.md)
5960
- [Custom Distribution](reference/metrics/custom_distribution.md)

‎docs/user/reference/metrics/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,8 @@ There are different metrics to choose from, depending on what you want to achiev
2828

2929
* [UUID](uuid.md): Used to record universally unique identifiers (UUIDs), such as a client ID.
3030

31+
* [URL](url.md): Used to record URL-like strings.
32+
3133
* [Datetime](datetime.md): Used to record an absolute date and time, such as the time the user first ran the application.
3234

3335
* [Events](event.md): Records events e.g. individual occurrences of user actions, say every time a view was open and from where.

‎docs/user/reference/metrics/url.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# URL
2+
3+
URL metrics allow recording URL-like[^1] strings.
4+
5+
This metric type does not support recording [data URLs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) - please get in contact with the Glean SDK team if you're missing a type.
6+
7+
{{#include ../../../shared/blockquote-warning.html}}
8+
9+
## Important
10+
11+
> Be careful using arbitrary URLs and make sure they can't accidentally contain identifying data
12+
> (like directory paths, user input or credentials).
13+
14+
[^1]: The Glean SDKs specifically do not validate if a URL is fully spec compliant,
15+
all the validations performed are the ones listed in the
16+
["Recorded errors"](#recorded-errors) section of this page.
17+
18+
## Recording API
19+
20+
### `set`
21+
22+
Set a URL metric to a specific string value.
23+
24+
{{#include ../../../shared/tab_header.md}}
25+
<div data-lang="Kotlin" class="tab"></div>
26+
<div data-lang="Java" class="tab"></div>
27+
<div data-lang="Swift" class="tab"></div>
28+
<div data-lang="Python" class="tab"></div>
29+
<div data-lang="Rust" class="tab"></div>
30+
<div data-lang="JavaScript" class="tab">
31+
32+
```js
33+
import * as search from "./path/to/generated/files/search.js";
34+
35+
search.template.set("https://mysearchengine.com/");
36+
```
37+
</div>
38+
<div data-lang="Firefox Desktop" class="tab"></div>
39+
{{#include ../../../shared/tab_footer.md}}
40+
41+
### `setUrl`
42+
43+
Set a URL metric to a specific URL value.
44+
45+
{{#include ../../../shared/tab_header.md}}
46+
<div data-lang="Kotlin" class="tab"></div>
47+
<div data-lang="Java" class="tab"></div>
48+
<div data-lang="Swift" class="tab"></div>
49+
<div data-lang="Python" class="tab"></div>
50+
<div data-lang="Rust" class="tab"></div>
51+
<div data-lang="JavaScript" class="tab">
52+
53+
```js
54+
import * as search from "./path/to/generated/files/search.js";
55+
56+
search.template.setUrl(new URL("https://mysearchengine.com/"));
57+
```
58+
</div>
59+
<div data-lang="Firefox Desktop" class="tab"></div>
60+
{{#include ../../../shared/tab_footer.md}}
61+
62+
#### Recorded errors
63+
64+
* [`invalid_value`](../../user/metrics/error-reporting.md):
65+
* If the URL passed does not start with a [scheme](https://url.spec.whatwg.org/#url-representation) followed by a `:` character.
66+
* If the URL passed uses the `data:` protocol.
67+
* [`invalid_overflow`](../../user/metrics/error-reporting.md): If the URL passed is longer than 2048 characters (before encoding).
68+
69+
#### Limits
70+
71+
* Fixed maximum URL length: 2048. Longer URLs are dropped.
72+
73+
## Testing API
74+
75+
### `testGetValue`
76+
77+
Gets the recorded value for a given URL metric as a (unencoded) string.
78+
79+
{{#include ../../../shared/tab_header.md}}
80+
81+
<div data-lang="Kotlin" class="tab"></div>
82+
<div data-lang="Java" class="tab"></div>
83+
<div data-lang="Swift" class="tab"></div>
84+
<div data-lang="Python" class="tab"></div>
85+
<div data-lang="Rust" class="tab"></div>
86+
<div data-lang="JavaScript" class="tab">
87+
88+
```js
89+
import * as search from "./path/to/generated/files/search.js";
90+
91+
assert.strictEqual(, await search.template.testGetValue());
92+
```
93+
</div>
94+
<div data-lang="Firefox Desktop" class="tab"></div>
95+
96+
{{#include ../../../shared/tab_footer.md}}
97+
98+
### `testGetNumRecordedErrors`
99+
100+
Gets number of errors recorded for a given counter metric.
101+
102+
{{#include ../../../shared/tab_header.md}}
103+
104+
<div data-lang="Kotlin" class="tab"></div>
105+
<div data-lang="Java" class="tab"></div>
106+
<div data-lang="Swift" class="tab"></div>
107+
<div data-lang="Python" class="tab"></div>
108+
<div data-lang="Rust" class="tab"></div>
109+
<div data-lang="JavaScript" class="tab">
110+
111+
```js
112+
import * as search from "./path/to/generated/files/search.js";
113+
import { ErrorType } from "@mozilla/glean/<platform>";
114+
115+
assert.strictEqual(
116+
0,
117+
await search.template.testGetNumRecordedErrors(ErrorType.InvalidValue)
118+
);
119+
assert.strictEqual(
120+
0,
121+
await search.template.testGetNumRecordedErrors(ErrorType.InvalidOverflow)
122+
);
123+
```
124+
</div>
125+
<div data-lang="Firefox Desktop" class="tab" data-info="Firefox Desktop uses testGetValue to communicate errors"></div>
126+
127+
{{#include ../../../shared/tab_footer.md}}
128+
129+
## Metric parameters
130+
131+
Example URL metric definition:
132+
133+
```yaml
134+
search:
135+
template:
136+
type: url
137+
description: >
138+
The base URL used to build the search query for the search engine.
139+
bugs:
140+
- https://bugzilla.mozilla.org/000000
141+
data_reviews:
142+
- https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
143+
notification_emails:
144+
- me@mozilla.com
145+
expires: 2020-10-01
146+
data_sensitivity:
147+
- web_activity
148+
```
149+
150+
For a full reference on metrics parameters common to all metric types,
151+
refer to the metrics [YAML format](../yaml/index.md) reference page.
152+
153+
{{#include ../../../shared/blockquote-warning.html}}
154+
155+
## Note on `data_sensitivity` of URL metrics
156+
157+
> URL metrics can only either be on categories 3 or 4, namely
158+
> ["Web activity data"](../yaml/metrics.md#category-3-web-activity-data-web_activity) or
159+
> ["Highly sensitive data"](../yaml/metrics.md#category-4-highly-sensitive-data-highly_sensitive).
160+
161+
### Extra metric parameters
162+
163+
N/A
164+
165+
## Data questions
166+
167+
* What is the base URL used to build the search query for the search engine?
168+
169+
## Reference
170+
171+
* [JavaScript API docs](https://mozilla.github.io/glean.js/classes/core_metrics_types_url.default.html)

0 commit comments

Comments
 (0)