Strings

String metrics allow recording a Unicode string value with arbitrary content.

This metric type does not support recording JSON blobs

  • please get in contact with the Glean team if you're missing a type.

Important

Be careful using arbitrary strings and make sure they can't accidentally contain identifying data (like directory paths or user input).

Recording API

set

Set a string metric to a specific value.

import org.mozilla.yourApplication.GleanMetrics.SearchDefault

// Record a value into the metric.
SearchDefault.name.set("duck duck go")
// If it changed later, you can record the new value:
SearchDefault.name.set("wikipedia")

import org.mozilla.yourApplication.GleanMetrics.SearchDefault;

// Record a value into the metric.
SearchDefault.INSTANCE.name().set("duck duck go");
// If it changed later, you can record the new value:
SearchDefault.INSTANCE.name().set("wikipedia");

// Record a value into the metric.
SearchDefault.name.set("duck duck go")
// If it changed later, you can record the new value:
SearchDefault.name.set("wikipedia")

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

# Record a value into the metric.
metrics.search_default.name.set("duck duck go")
# If it changed later, you can record the new value:
metrics.search_default.name.set("wikipedia")

use glean_metrics::search_default;

// Record a value into the metric.
search_default::name.set("duck duck go");
// If it changed later, you can record the new value:
search_default::name.set("wikipedia");

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

// Record a value into the metric.
searchDefault.name.set("duck duck go");
// If it changed later, you can record the new value:
searchDefault.name.set("wikipedia");

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::search_default::name.Set("wikipedia"_ns);

JavaScript

Glean.searchDefault.name.set("wikipedia");

Recorded errors

  • invalid_overflow: if the string is too long. (Prior to Glean 31.5.0, this recorded an invalid_value).
  • invalid_type: if a non-string value is given.

Limits

  • Fixed maximum string length: 100. Longer strings are truncated. This is measured in the number of bytes when the string is encoded in UTF-8.

Testing API

testGetValue

Get the recorded value for a given string metric.
Returns the string if data is stored.
Returns a language-specific empty/null value if no data is stored.

The recorded value may have been truncated. See "Limits" section above.

import org.mozilla.yourApplication.GleanMetrics.SearchDefault

// Does the string metric have the expected value?
assertEquals("wikipedia", SearchDefault.name.testGetValue())

import org.mozilla.yourApplication.GleanMetrics.SearchDefault;

// Does the string metric have the expected value?
assertEquals("wikipedia", SearchDefault.INSTANCE.name().testGetValue());

// Does the string metric have the expected value?
XCTAssertEqual("wikipedia", SearchDefault.name.testGetValue())

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

# Does the string metric have the expected value?
assert "wikipedia" == metrics.search_default.name.test_get_value()

use glean_metrics::search_default;

// Does the string metric have the expected value?
assert_eq!(6, search_default::name.test_get_value(None).unwrap());

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

assert.strictEqual("wikipedia", await searchDefault.name.testGetValue());

C++

#include "mozilla/glean/GleanMetrics.h"

// Is it clear of errors?
ASSERT_TRUE(mozilla::glean::search_default::name.TestGetValue().isOk());
// Does it have the expected value?
ASSERT_STREQ(
  "wikipedia",
  mozilla::glean::search_default::name.TestGetValue().unwrap().value().get()
);

JavaScript

// Does it have the expected value?
// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
Assert.equal("wikipedia", Glean.searchDefault.name.testGetValue());

testGetNumRecordedErrors

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

import org.mozilla.yourApplication.GleanMetrics.SearchDefault

// Was the string truncated, and an error reported?
assertEquals(
    0,
    SearchDefault.name.testGetNumRecordedErrors(ErrorType.INVALID_OVERFLOW)
)

import org.mozilla.yourApplication.GleanMetrics.SearchDefault;

// Was the string truncated, and an error reported?
assertEquals(
    0,
    SearchDefault.INSTANCE.name().testGetNumRecordedErrors(ErrorType.INVALID_OVERFLOW)
);

// Was the string truncated, and an error reported?
XCTAssertEqual(0, SearchDefault.name.testGetNumRecordedErrors(.invalidOverflow))

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

# Was the string truncated, and an error reported?
assert 0 == metrics.search_default.name.test_get_num_recorded_errors(
    ErrorType.INVALID_OVERFLOW
)

use glean::ErrorType;
use glean_metrics::search_default;

// Was the string truncated, and an error reported?
assert_eq!(
  0,
  search_default::name.test_get_num_recorded_errors(
    ErrorType::InvalidOverflow
  )
);

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

// Was the string truncated, and an error reported?
assert.strictEqual(
  0,
  await searchDefault.name.testGetNumRecordedErrors(ErrorType.InvalidOverflow)
);

Metric parameters

Example string metric definition:

controls:
  refresh_pressed:
    type: string
    description: >
      The name of the default search engine.
    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 registry format reference page.

Extra metric parameters

N/A

Data questions

  • Record the operating system name with a value of "android".

  • Recording the device model with a value of "SAMSUNG-SGH-I997".

Reference