Struct glean::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(),
    language_binding_name: "Rust".into(),
    upload_enabled: true,
    max_events: None,
    delay_ping_lifetime_io: false,
};
let mut glean = Glean::new(cfg).unwrap();
let ping = PingType::new("sample", true, false, vec![]);
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.submit_ping(&ping, None).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.

Implementations

impl Glean

pub fn new_for_subprocess(
    cfg: &Configuration,
    scan_directories: bool
) -> Result<Glean, Error>

Creates and initializes a new Glean object for use in a subprocess.

Importantly, this will not send any pings at startup, since that sort of management should only happen in the main process.

pub fn new(cfg: Configuration) -> Result<Glean, Error>

Creates and initializes a new Glean object.

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

pub fn destroy_db(&mut self)

Destroys the database.

After this Glean needs to be reinitialized.

pub fn on_ready_to_submit_pings(&self) -> bool

Signals that the environment is ready to submit pings.

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

Returns

Whether at least one ping was generated.

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

Sets 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

Whether 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

Determines whether upload is enabled.

When upload is disabled, no data will be recorded.

pub fn get_application_id(&self) -> &str

Gets the application ID as specified on instantiation.

pub fn get_data_path(&self) -> &Path

Gets the data path of this instance.

pub fn storage(&self) -> &Database

Gets a handle to the database.

pub fn event_storage(&self) -> &EventDatabase

Gets a handle to the event database.

pub fn get_max_events(&self) -> usize

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

pub fn get_upload_task(&self) -> PingUploadTask

Gets the next task for an uploader.

This can be one of:

• Wait - which means the requester should ask again later;
• Upload(PingRequest) - which means there is a ping to upload. This wraps the actual request object;
• Done - which means requester should stop asking for now.

Returns

A PingUploadTask representing the next task.

pub fn process_ping_upload_response(&self, uuid: &str, status: UploadResult)

Processes the response from an attempt to upload a ping.

Arguments

• uuid - The UUID of the ping in question.
• status - The upload result.

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

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

Returns

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

pub fn submit_ping(
    &self,
    ping: &PingType,
    reason: Option<&str>
) -> Result<bool, Error>

Collects and submits a ping for eventual uploading.

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, unless it is configured to be sent if empty.

Arguments

• ping - The ping to submit
• reason - A reason code to include in the ping

Returns

Whether the ping was succesfully assembled and queued.

Errors

If collecting or writing the ping to disk failed.

pub fn submit_ping_by_name(
    &self,
    ping_name: &str,
    reason: Option<&str>
) -> Result<bool, Error>

Collects and submits a ping by name for eventual uploading.

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, unless it is configured to be sent if empty.

Arguments

• ping_name - The name of the ping to submit
• reason - A reason code to include in the ping

Returns

Whether the ping was succesfully assembled and queued.

Errors

If collecting or writing the ping to disk failed.

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

Gets a PingType by name.

Returns

The PingType of a ping if the given name was registered before, 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, RandomState>>
)

Indicates 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)

Indicates that an experiment is no longer running.

Arguments

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

pub fn persist_ping_lifetime_data(&self) -> Result<(), Error>

Persists Lifetime::Ping data that might be in memory in case delay_ping_lifetime_io is set or was set at a previous time.

If there is no data to persist, this function does nothing.

pub fn clear_application_lifetime_metrics(&self)

This is not meant to be used directly.

Clears all the metrics that have Lifetime::Application.

pub fn is_first_run(&self) -> bool

Whether or not this is the first run on this profile.

pub fn set_debug_view_tag(&mut self, value: &str) -> bool

Sets a debug view tag.

This will return false in case value is not a valid tag.

When the debug view tag is set, pings are sent with a X-Debug-ID header with the value of the tag and are sent to the "Ping Debug Viewer".

Arguments

• value - A valid HTTP header value. Must match the regex: "[a-zA-Z0-9-]{1,20}".

pub fn set_source_tags(&mut self, value: Vec<String, Global>) -> bool

Sets source tags.

This will return false in case value contains invalid tags.

Ping tags will show in the destination datasets, after ingestion.

Arguments

• value - A vector of at most 5 valid HTTP header values. Individual tags must match the regex: "[a-zA-Z0-9-]{1,20}".

pub fn set_log_pings(&mut self, value: bool) -> bool

Sets the log pings debug option.

This will return false in case we are unable to set the option.

When the log pings debug option is true, we log the payload of all succesfully assembled pings.

Arguments

• value - The value of the log pings option

pub fn set_dirty_flag(&self, new_value: bool)

This is not meant to be used directly.

Sets the value of a "dirty flag" in the permanent storage.

The "dirty flag" is meant to have the following behaviour, implemented by the consumers of the FFI layer:

• on mobile: set to false when going to background or shutting down, set to true at startup and when going to foreground.
• on non-mobile platforms: set to true at startup and false at shutdown.

At startup, before setting its new value, if the "dirty flag" value is true, then Glean knows it did not exit cleanly and can implement coping mechanisms (e.g. sending a baseline ping).

pub fn is_dirty_flag_set(&self) -> bool

This is not meant to be used directly.

Checks the stored value of the "dirty flag".

pub fn handle_client_active(&mut self)

Performs the collection/cleanup operations required by becoming active.

This functions generates a baseline ping with reason active and then sets the dirty bit.

pub fn handle_client_inactive(&mut self)

Performs the collection/cleanup operations required by becoming inactive.

This functions generates a baseline and an events ping with reason inactive and then clears the dirty bit.

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

Test-only API (exported for FFI purposes).

Checks if an experiment is currently active.

Arguments

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

Returns

Whether the experiment is active.

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

Test-only API (exported for FFI purposes).

Gets stored data for the requested experiment.

Arguments

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

Returns

A JSON string with the following format:

{ 'branch': 'the-branch-name', 'extra': {'key': 'value', ...}}

if the requested experiment is active, None otherwise.

pub fn test_clear_all_stores(&self)

Test-only API (exported for FFI purposes).

Deletes 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

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.