Labeled Strings

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

Configuration

For example to record which kind of error occurred in different stages of a login process - "RuntimeException" in the "server_auth" stage or "invalid_string" in the "enter_email" stage:

login:
  errors_by_stage:
    type: labeled_string
    description: Records the error type, if any, that occur in different stages of the login process.
    labels:
      - server_auth
      - enter_email
    ...

API

Now you can use the labeled string from the application's code:

import org.mozilla.yourApplication.GleanMetrics.Login

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

There are test APIs available too:

import org.mozilla.yourApplication.GleanMetrics.Login

// Was anything recorded?
assertTrue(Login.errorsByStage["server_auth"].testHasValue())

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

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

There are test APIs available too:

@testable import Glean

// Was anything recorded?
XCTAssert(Login.errorsByStage["server_auth"].testHasValue())

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

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

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

There are test APIs available too:

# Was anything recorded?
assert metrics.login.errors_by_stage["server_auth"].test_has_value()

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

using static Mozilla.YourApplication.GleanMetrics.Login;

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

There are test APIs available too:

using static Mozilla.YourApplication.GleanMetrics.Login;

// Was anything recorded?
Assert.True(Login.errorsByStage["server_auth"].TestHasValue());

// Were there any invalid labels?
Assert.Equal(0, Login.errorsByStage.TestGetNumRecordedErrors(ErrorType.InvalidLabel));


#![allow(unused)]
fn main() {
use glean_metrics;

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

There are test APIs available too:


#![allow(unused)]
fn main() {
use glean::ErrorType;

use glean_metrics;

// Was anything recorded?
assert!(login::errors_by_stage.get("server_auth").test_get_value().is_sone());

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

Limits

  • Labels must conform to the label formatting regular expression.

  • Labels support lowercase alphanumeric characters; they additionally allow for dots (.), underscores (_) and/or hyphens (-).

  • Each label must have a maximum of 60 bytes, when encoded as UTF-8.

  • 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__.

  • The number of labels specified in the metrics.yaml is limited to 100.

  • If the labels aren't specified in the metrics.yaml, only 16 different dynamic labels may be used, after which the special value __other__ will be used.

Examples

  • What kind of errors occurred at each step in the login process?

Recorded Errors

  • invalid_label: If the label contains invalid characters. Data is still recorded to the special label __other__.

  • invalid_label: If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label __other__.

Reference