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
)

TODO. To be implemented in bug 1648438.

Limits

  • Labels must conform to the label formatting regular expression.

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

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

  • invalid_label: If the label exceeds the maximum number of allowed characters.

Reference