Struct glean_core::Glean

pub struct Glean { /* fields omitted */ }

The object holding meta information about a Glean instance.

Example

Create a new Glean instance, register a ping, record a simple counter and then send the final ping.

let cfg = Configuration {
    data_path: "/tmp/glean".into(),
    application_id: "glean.sample.app".into(),
    upload_enabled: true,
    max_events: None,
};
let mut glean = Glean::new(cfg).unwrap();
let ping = PingType::new("sample", true);
glean.register_ping_type(&ping);

let call_counter: CounterMetric = CounterMetric::new(CommonMetricData {
    name: "calls".into(),
    category: "local".into(),
    send_in_pings: vec!["sample".into()],
    ..Default::default()
});

call_counter.add(&glean, 1);

glean.send_ping(&ping).unwrap();

Note

In specific language bindings, this is usually wrapped in a singleton and all metric recording goes to a single instance of this object. In the Rust core, it is possible to create multiple instances, which is used in testing.

Methods

impl Glean

pub fn new(cfg: Configuration) -> Result<Self>

Create and initialize a new Glean object.

This will create the necessary directories and files in data_path. This will also initialize the core metrics.

pub fn with_sequence_numbers(
    cfg: Configuration,
    new_sequence_nums: HashMap<String, i32>
) -> Result<Self>

Create and initialize a new Glean object.

This will attempt to delete any previously existing database and then create the necessary directories and files in data_path. This will also initialize the core metrics.

Arguments

• cfg - an instance of the Glean Configuration.
• new_sequence_nums - a map of ("_seq", sequence number) used to initialize Glean with sequence numbers imported from glean-ac.

pub fn on_ready_to_send_pings(&self) -> bool

Called when Glean is initialized to the point where it can correctly assemble pings. Usually called from the language specific layer after all of the core metrics have been set and the ping types have been registered.

Return value

true if at least one ping was generated, false otherwise.

pub fn set_upload_enabled(&mut self, flag: bool) -> bool

Set whether upload is enabled or not.

When uploading is disabled, metrics aren't recorded at all and no data is uploaded.

When disabling, all pending metrics, events and queued pings are cleared.

When enabling, the core Glean metrics are recreated.

If the value of this flag is not actually changed, this is a no-op.

Arguments

• flag - When true, enable metric collection.

Returns

• Returns true when the flag was different from the current value, and actual work was done to clear or reinstate metrics.

pub fn is_upload_enabled(&self) -> bool

Determine whether upload is enabled.

When upload is disabled, no data will be recorded.

pub fn get_application_id(&self) -> &str

Get the application ID as specified on instantiation.

pub fn get_data_path(&self) -> &Path

Get the data path of this instance.

pub fn storage(&self) -> &Database

Get a handle to the database.

pub fn event_storage(&self) -> &EventDatabase

Get a handle to the event database.

pub fn get_max_events(&self) -> usize

Get the maximum number of events to store before sending a ping.

pub fn snapshot(&mut self, store_name: &str, clear_store: bool) -> String

Take a snapshot for the given store and optionally clear it.

Arguments

• store_name - The store to snapshot.
• clear_store - Whether to clear the store after snapshotting.

Return value

Returns the snapshot in a string encoded as JSON. If the snapshot is empty, it returns an empty string.

pub fn send_ping(&self, ping: &PingType) -> Result<bool>

Send a ping.

The ping content is assembled as soon as possible, but upload is not guaranteed to happen immediately, as that depends on the upload policies.

If the ping currently contains no content, it will not be sent.

Returns true if a ping was assembled and queued, false otherwise. Returns an error if collecting or writing the ping to disk failed.

pub fn send_pings_by_name(&self, ping_names: &[String]) -> bool

Send a list of pings by name.

See send_ping for detailed information.

Returns true if at least one ping was assembled and queued, false otherwise.

pub fn send_ping_by_name(&self, ping_name: &str) -> Result<bool>

Send a ping by name.

The ping content is assembled as soon as possible, but upload is not guaranteed to happen immediately, as that depends on the upload policies.

If the ping currently contains no content, it will not be sent.

Returns true if a ping was assembled and queued, false otherwise. Returns an error if collecting or writing the ping to disk failed.

pub fn get_ping_by_name(&self, ping_name: &str) -> Option<&PingType>

Get a PingType by name.

Return value

Returns the PingType if a ping of the given name was registered before. Returns None otherwise.

pub fn register_ping_type(&mut self, ping: &PingType)

Register a new PingType.

pub fn set_experiment_active(
    &self,
    experiment_id: String,
    branch: String,
    extra: Option<HashMap<String, String>>
)

Indicate that an experiment is running. Glean will then add an experiment annotation to the environment which is sent with pings. This information is not persisted between runs.

Arguments

• experiment_id - The id of the active experiment (maximum 30 bytes).
• branch - The experiment branch (maximum 30 bytes).
• extra - Optional metadata to output with the ping.

pub fn set_experiment_inactive(&self, experiment_id: String)

Indicate that an experiment is no longer running.

Arguments

• experiment_id - The id of the active experiment to deactivate (maximum 30 bytes).

pub fn test_is_experiment_active(&self, experiment_id: String) -> bool

Test-only API (exported for FFI purposes).

Check if an experiment is currently active.

Arguments

• experiment_id - The id of the experiment (maximum 30 bytes).

Return value

True if the experiment is active, false otherwise.

pub fn test_get_experiment_data_as_json(
    &self,
    experiment_id: String
) -> Option<String>

Test-only API (exported for FFI purposes).

Get stored data for the requested experiment.

Arguments

• experiment_id - The id of the active experiment (maximum 30 bytes).

Return value

If the requested experiment is active, a JSON string with the following format: { 'branch': 'the-branch-name', 'extra': {'key': 'value', ...}} Otherwise, None.

pub fn test_clear_all_stores(&self)

Test-only API (exported for FFI purposes).

Delete all stored metrics. Note that this also includes the ping sequence numbers, so it has the effect of resetting those to their initial values.

Trait Implementations

impl Debug for Glean

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.