Labeled Strings

Labeled strings record multiple Unicode string values, each under a different label.

Recording API

`set`

Sets one of the labels in a labeled string metric to a specific value.

import org.mozilla.yourApplication.GleanMetrics.Login

Login.errorsByStage["server_auth"].set("Invalid password")

import org.mozilla.yourApplication.GleanMetrics.Login;

Login.INSTANCE.errorsByStage()["server_auth"].set("Invalid password");

Login.errorsByStage["server_auth"].set("Invalid password")

from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.login.errors_by_stage["server_auth"].set("Invalid password")

use glean_metrics::login;

login::errors_by_stage.get("server_auth").set("Invalid password");

import * as login from "./path/to/generated/files/login.js";

login.errorsByStage["server_auth"].set("Invalid password");

C++

#include "mozilla/glean/DomWebauthnMetrics.h"

mozilla::glean::login::errors_by_stage.Get("server_auth"_ns).Set("Invalid password"_ns);

JavaScript

Glean.login.errorsByStage["server_auth"].set("Invalid password");

Recorded Errors

invalid_overflow:
- If the string value is too long. (Prior to Glean v31.5.0 this was recorded as invalid_value.)
invalid_type:
- If a non-string value is provided.
invalid_label:
- If the label contains invalid characters. Data is still recorded to the special label __other__.
- If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label __other__.

Limits

String values must not exceed 255 bytes of UTF-8. Longer strings will be truncated.
- Prior to Glean v60.4.0 the limit was 100 bytes.
Labels must conform to the label format.
Each label must have a maximum of 111 characters.
The list of labels is limited to:
- 16 different dynamic labels if no static labels are defined. Additional labels will all record to the special label __other__. These labels may contain any UTF-8 characters.
- 100 labels if specified as static labels in metrics.yaml, see Labels. Unknown labels will be recorded under the special label __other__. These labels may only be made of printable ASCII characters.

Gets the recorded value for a given label in a labeled string metric.
Returns the string if data is stored.
Returns a language-specific empty/null value if no data is stored. Has an optional argument to specify the name of the ping you wish to retrieve data from, except in Rust where it's required. None or no argument will default to the first value found for send_in_pings.

import org.mozilla.yourApplication.GleanMetrics.Login

// Does the metric have the expected value?
assertTrue(Login.errorsByStage["server_auth"].testGetValue())

import org.mozilla.yourApplication.GleanMetrics.Login;

// Does the metric have the expected value?
assertTrue(Login.INSTANCE.errorsByStage()["server_auth"].testGetValue());

// Does the metric have the expected value?
XCTAssert(Login.errorsByStage["server_auth"].testGetValue())

from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Does the metric have the expected value?
assert "Invalid password" == metrics.login.errors_by_stage["server_auth"].testGetValue())

use glean_metrics::login;

// Does the metric have the expected value?
assert!(login::errors_by_stage.get("server_auth").test_get_value());

import * as login from "./path/to/generated/files/login.js";

// Does the metric have the expected value?
assert.strictEqual("Invalid password", await metrics.login.errorsByStage["server_auth"].testGetValue())

C++

#include "mozilla/glean/DomWebauthnMetrics.h"

ASSERT_STREQ("Invalid password",
             mozilla::glean::login::errors_by_stage.Get("server_auth"_ns)
                .TestGetValue()
                .unwrap()
                .ref()
                .get());

JavaScript

Assert.equal("Invalid password", Glean.login.errorsByStage["server_auth"].testGetValue());

`testGetNumRecordedErrors`

Gets the number of errors recorded for a given labeled string metric in total.

import org.mozilla.yourApplication.GleanMetrics.Login

// Were there any invalid labels?
assertEquals(
    0,
    Login.errorsByStage.testGetNumRecordedErrors(ErrorType.INVALID_LABEL)
)

import org.mozilla.yourApplication.GleanMetrics.Login;

// Were there any invalid labels?
assertEquals(
    0,
    Login.INSTANCE.errorsByStage().testGetNumRecordedErrors(ErrorType.INVALID_LABEL)
);

// Were there any invalid labels?
XCTAssertEqual(0, Login.errorsByStage.testGetNumRecordedErrors(.invalidLabel))

from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Were there any invalid labels?
assert 0 == metrics.login.errors_by_stage.test_get_num_recorded_errors(
    ErrorType.INVALID_LABEL
)

use glean::ErrorType;
use glean_metrics::login;

// Were there any invalid labels?
assert_eq!(
  0,
  login::errors_by_stage.test_get_num_recorded_errors(
    ErrorType::InvalidLabel
  )
);

import * as login from "./path/to/generated/files/login.js";
import { ErrorType } from "@mozilla/glean/error";

// Were there any invalid labels?
assert(
  0,
  await login.errorsByStage.testGetNumRecordedErrors(ErrorType.InvalidLabel)
);

Metric parameters

Example labeled boolean metric definition:

login:
  errors_by_stage:
    type: labeled_string
    description: Records the error type, if any, that occur in different stages of the login process.
    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
    labels:
      - server_auth
      - enter_email
      ...

Extra metric parameters

`labels`

Labeled metrics may have an optional labels parameter, containing a list of known labels. The labels in this list must match the following requirements:

Conform to the label format.
Each label must have a maximum of 111 characters.
Each label must only contain printable ASCII characters.
This list itself is limited to 4096 labels.

Important

If the labels are specified in the metrics.yaml, using any label not listed in that file will be replaced with the special value __other__.

If the labels are not specified in the metrics.yaml, only 16 different dynamic labels may be used, after which the special value __other__ will be used.

Removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels that were removed in the past. It is best practice to add documentation about removed labels to the description field so that analysts will know of their existence and meaning in historical data. Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the index of the labels is used to report Gecko data through the Glean SDK.