Struct glean::Glean [−][src]
pub struct Glean { /* fields omitted */ }
Expand description
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,
app_build: "".into(),
use_core_mps: 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);
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
pub fn new_for_subprocess(
cfg: &Configuration,
scan_directories: bool
) -> Result<Glean, Error>
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.
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.
Destroys the database.
After this Glean needs to be reinitialized.
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.
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.
Determines whether upload is enabled.
When upload is disabled, no data will be recorded.
Gets the application ID as specified on instantiation.
Gets the data path of this instance.
Gets a handle to the event database.
Gets the maximum number of events to store before sending a ping.
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.
Processes the response from an attempt to upload a ping.
Arguments
uuid
- The UUID of the ping in question.status
- The upload result.
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 submitreason
- A reason code to include in the ping
Returns
Whether the ping was succesfully assembled and queued.
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 submitreason
- 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.
Register a new PingType
.
pub fn set_experiment_active(
&self,
experiment_id: String,
branch: String,
extra: Option<HashMap<String, String, RandomState>>
)
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.
Indicates that an experiment is no longer running.
Arguments
experiment_id
- The id of the active experiment to deactivate (maximum 30 bytes).
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.
This is not meant to be used directly.
Clears all the metrics that have Lifetime::Application
.
Whether or not this is the first run on this profile.
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}”.
Sets source tags.
This will return false
in case value
contains invalid tags.
Ping tags will show in the destination datasets, after ingestion.
Note If one or more tags are invalid, all tags are ignored.
Arguments
value
- A vector of at most 5 valid HTTP header values. Individual tags must match the regex: “[a-zA-Z0-9-]{1,20}”.
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
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 totrue
at startup and when going to foreground. - on non-mobile platforms: set to
true
at startup andfalse
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).
This is not meant to be used directly.
Checks the stored value of the “dirty flag”.
Performs the collection/cleanup operations required by becoming active.
This functions generates a baseline ping with reason active
and then sets the dirty bit.
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.
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.
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.
Instructs the Metrics Ping Scheduler’s thread to exit cleanly.
If Glean was configured with use_core_mps: false
, this has no effect.
Instructs the Metrics Ping Scheduler to being scheduling metrics pings.
If Glean wsa configured with use_core_mps: false
, this has no effect.