third_party/rust/glean/src/configuration.rs

   1 // This Source Code Form is subject to the terms of the Mozilla Public
   2 // License, v. 2.0. If a copy of the MPL was not distributed with this
   3 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
   4
   5 use log::LevelFilter;
   6
   7 use crate::net::PingUploader;
   8
   9 use std::path::PathBuf;
  10
  11 /// The default server pings are sent to.
  12 pub(crate) const DEFAULT_GLEAN_ENDPOINT: &str = "https://incoming.telemetry.mozilla.org";
  13
  14 /// The Glean configuration.
  15 ///
  16 /// Optional values will be filled in with default values.
  17 #[derive(Debug)]
  18 pub struct Configuration {
  19     /// Whether upload should be enabled.
  20     pub upload_enabled: bool,
  21     /// Path to a directory to store all data in.
  22     pub data_path: PathBuf,
  23     /// The application ID (will be sanitized during initialization).
  24     pub application_id: String,
  25     /// The maximum number of events to store before sending a ping containing events.
  26     pub max_events: Option<usize>,
  27     /// Whether Glean should delay persistence of data from metrics with ping lifetime.
  28     pub delay_ping_lifetime_io: bool,
  29     /// The server pings are sent to.
  30     pub server_endpoint: Option<String>,
  31     /// The instance of the uploader used to send pings.
  32     pub uploader: Option<Box<dyn PingUploader + 'static>>,
  33     /// Whether Glean should schedule "metrics" pings for you.
  34     pub use_core_mps: bool,
  35     /// Whether Glean should limit its storage to only that of registered pings.
  36     /// Unless you know that all your and your libraries' pings are appropriately registered
  37     /// _before_ init, you shouldn't use this.
  38     pub trim_data_to_registered_pings: bool,
  39     /// The internal logging level.
  40     pub log_level: Option<LevelFilter>,
  41     /// The rate pings may be uploaded before they are throttled.
  42     pub rate_limit: Option<crate::PingRateLimit>,
  43     /// (Experimental) Whether to add a wallclock timestamp to all events.
  44     pub enable_event_timestamps: bool,
  45     /// An experimentation identifier derived by the application to be sent with all pings, it should
  46     /// be noted that this has an underlying StringMetric and so should conform to the limitations that
  47     /// StringMetric places on length, etc.
  48     pub experimentation_id: Option<String>,
  49 }
  50
  51 /// Configuration builder.
  52 ///
  53 /// Let's you build a configuration from the required fields
  54 /// and let you set optional fields individually.
  55 #[derive(Debug)]
  56 pub struct Builder {
  57     /// Required: Whether upload should be enabled.
  58     pub upload_enabled: bool,
  59     /// Required: Path to a directory to store all data in.
  60     pub data_path: PathBuf,
  61     /// Required: The application ID (will be sanitized during initialization).
  62     pub application_id: String,
  63     /// Optional: The maximum number of events to store before sending a ping containing events.
  64     /// Default: `None`
  65     pub max_events: Option<usize>,
  66     /// Optional: Whether Glean should delay persistence of data from metrics with ping lifetime.
  67     /// Default: `false`
  68     pub delay_ping_lifetime_io: bool,
  69     /// Optional: The server pings are sent to.
  70     /// Default: `None`
  71     pub server_endpoint: Option<String>,
  72     /// Optional: The instance of the uploader used to send pings.
  73     /// Default: `None`
  74     pub uploader: Option<Box<dyn PingUploader + 'static>>,
  75     /// Optional: Whether Glean should schedule "metrics" pings for you.
  76     /// Default: `false`
  77     pub use_core_mps: bool,
  78     /// Optional: Whether Glean should limit its storage to only that of registered pings.
  79     /// Unless you know that all your and your libraries' pings are appropriately registered
  80     /// _before_ init, you shouldn't use this.
  81     /// Default: `false`
  82     pub trim_data_to_registered_pings: bool,
  83     /// Optional: The internal logging level.
  84     /// Default: `None`
  85     pub log_level: Option<LevelFilter>,
  86     /// Optional: The internal ping upload rate limit.
  87     /// Default: `None`
  88     pub rate_limit: Option<crate::PingRateLimit>,
  89     /// (Experimental) Whether to add a wallclock timestamp to all events.
  90     pub enable_event_timestamps: bool,
  91     /// An experimentation identifier derived by the application to be sent with all pings, it should
  92     /// be noted that this has an underlying StringMetric and so should conform to the limitations that
  93     /// StringMetric places on length, etc.
  94     pub experimentation_id: Option<String>,
  95 }
  96
  97 impl Builder {
  98     /// A new configuration builder.
  99     pub fn new<P: Into<PathBuf>, S: Into<String>>(
 100         upload_enabled: bool,
 101         data_path: P,
 102         application_id: S,
 103     ) -> Self {
 104         Self {
 105             upload_enabled,
 106             data_path: data_path.into(),
 107             application_id: application_id.into(),
 108             max_events: None,
 109             delay_ping_lifetime_io: false,
 110             server_endpoint: None,
 111             uploader: None,
 112             use_core_mps: false,
 113             trim_data_to_registered_pings: false,
 114             log_level: None,
 115             rate_limit: None,
 116             enable_event_timestamps: true,
 117             experimentation_id: None,
 118         }
 119     }
 120
 121     /// Generate the full configuration.
 122     pub fn build(self) -> Configuration {
 123         Configuration {
 124             upload_enabled: self.upload_enabled,
 125             data_path: self.data_path,
 126             application_id: self.application_id,
 127             max_events: self.max_events,
 128             delay_ping_lifetime_io: self.delay_ping_lifetime_io,
 129             server_endpoint: self.server_endpoint,
 130             uploader: self.uploader,
 131             use_core_mps: self.use_core_mps,
 132             trim_data_to_registered_pings: self.trim_data_to_registered_pings,
 133             log_level: self.log_level,
 134             rate_limit: self.rate_limit,
 135             enable_event_timestamps: self.enable_event_timestamps,
 136             experimentation_id: self.experimentation_id,
 137         }
 138     }
 139
 140     /// Set the maximum number of events to store before sending a ping containing events.
 141     pub fn with_max_events(mut self, max_events: usize) -> Self {
 142         self.max_events = Some(max_events);
 143         self
 144     }
 145
 146     /// Set whether Glean should delay persistence of data from metrics with ping lifetime.
 147     pub fn with_delay_ping_lifetime_io(mut self, value: bool) -> Self {
 148         self.delay_ping_lifetime_io = value;
 149         self
 150     }
 151
 152     /// Set the server pings are sent to.
 153     pub fn with_server_endpoint<S: Into<String>>(mut self, server_endpoint: S) -> Self {
 154         self.server_endpoint = Some(server_endpoint.into());
 155         self
 156     }
 157
 158     /// Set the instance of the uploader used to send pings.
 159     pub fn with_uploader<U: PingUploader + 'static>(mut self, uploader: U) -> Self {
 160         self.uploader = Some(Box::new(uploader));
 161         self
 162     }
 163
 164     /// Set whether Glean should schedule "metrics" pings for you.
 165     pub fn with_use_core_mps(mut self, value: bool) -> Self {
 166         self.use_core_mps = value;
 167         self
 168     }
 169
 170     /// Set whether Glean should limit its storage to only that of registered pings.
 171     pub fn with_trim_data_to_registered_pings(mut self, value: bool) -> Self {
 172         self.trim_data_to_registered_pings = value;
 173         self
 174     }
 175
 176     /// Set whether to add a wallclock timestamp to all events (experimental).
 177     pub fn with_event_timestamps(mut self, value: bool) -> Self {
 178         self.enable_event_timestamps = value;
 179         self
 180     }
 181
 182     /// Set whether to add a wallclock timestamp to all events (experimental).
 183     pub fn with_experimentation_id(mut self, value: String) -> Self {
 184         self.experimentation_id = Some(value);
 185         self
 186     }
 187 }