1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at https://mozilla.org/MPL/2.0/.
use std::borrow::Cow;
use std::char;
use std::collections::{HashMap, HashSet};
use std::mem;
use std::sync::{Arc, Mutex};
use crate::common_metric_data::{CommonMetricData, CommonMetricDataInternal, DynamicLabelType};
use crate::error_recording::{record_error, test_get_num_recorded_errors, ErrorType};
use crate::metrics::{CounterMetric, Metric, MetricType};
use crate::Glean;
const MAX_LABELS: usize = 16;
const OTHER_LABEL: &str = "__other__";
const MAX_LABEL_LENGTH: usize = 111;
pub(crate) const RECORD_SEPARATOR: char = '\x1E';
/// A dual labled metric
///
/// Dual labled metrics allow recording multiple sub-metrics of the same type, in relation
/// to two dimensions rather than the single label provided by the standard labeled type.
#[derive(Debug)]
pub struct DualLabeledCounterMetric {
keys: Option<Vec<Cow<'static, str>>>,
categories: Option<Vec<Cow<'static, str>>>,
/// Type of the underlying metric
/// We hold on to an instance of it, which is cloned to create new modified instances.
counter: CounterMetric,
/// A map from a unique ID for the dual labeled submetric to a handle of an instantiated
/// metric type.
dual_label_map: Mutex<HashMap<(String, String), Arc<CounterMetric>>>,
}
impl ::malloc_size_of::MallocSizeOf for DualLabeledCounterMetric {
fn size_of(&self, ops: &mut malloc_size_of::MallocSizeOfOps) -> usize {
let mut n = 0;
n += self.keys.size_of(ops);
n += self.categories.size_of(ops);
n += self.counter.size_of(ops);
// `MallocSizeOf` is not implemented for `Arc<CounterMetric>`,
// so we reimplement counting the size of the hashmap ourselves.
let map = self.dual_label_map.lock().unwrap();
// Copy of `MallocShallowSizeOf` implementation for `HashMap<K, V>` in `wr_malloc_size_of`.
// Note: An instantiated submetric is behind an `Arc`.
// `size_of` should only be called from a single thread to avoid double-counting.
let shallow_size = if ops.has_malloc_enclosing_size_of() {
map.values()
.next()
.map_or(0, |v| unsafe { ops.malloc_enclosing_size_of(v) })
} else {
map.capacity()
* (mem::size_of::<String>() // key
+ mem::size_of::<Arc<CounterMetric>>() // allocation for the `Arc` value
+ mem::size_of::<CounterMetric>() // allocation for the `CounterMetric` value
// within the `Arc`
+ mem::size_of::<usize>())
};
let mut map_size = shallow_size;
for (k, v) in map.iter() {
map_size += k.size_of(ops);
map_size += v.size_of(ops);
}
n += map_size;
n
}
}
impl MetricType for DualLabeledCounterMetric {
fn meta(&self) -> &CommonMetricDataInternal {
self.counter.meta()
}
}
impl DualLabeledCounterMetric {
/// Creates a new dual labeled counter from the given metric instance and optional list of labels.
pub fn new(
meta: CommonMetricData,
keys: Option<Vec<Cow<'static, str>>>,
catgories: Option<Vec<Cow<'static, str>>>,
) -> DualLabeledCounterMetric {
let submetric = CounterMetric::new(meta);
DualLabeledCounterMetric::new_inner(submetric, keys, catgories)
}
fn new_inner(
counter: CounterMetric,
keys: Option<Vec<Cow<'static, str>>>,
categories: Option<Vec<Cow<'static, str>>>,
) -> DualLabeledCounterMetric {
let dual_label_map = Default::default();
DualLabeledCounterMetric {
keys,
categories,
counter,
dual_label_map,
}
}
/// Creates a new metric with a specific key and category, validating against
/// the static or dynamic labels where needed.
fn new_counter_metric(&self, key: &str, category: &str) -> CounterMetric {
match (&self.keys, &self.categories) {
(None, None) => self
.counter
.with_dynamic_label(DynamicLabelType::KeyAndCategory(
make_label_from_key_and_category(key, category),
)),
(None, _) => {
let static_category = self.static_category(category);
self.counter.with_dynamic_label(DynamicLabelType::KeyOnly(
make_label_from_key_and_category(key, static_category),
))
}
(_, None) => {
let static_key = self.static_key(key);
self.counter
.with_dynamic_label(DynamicLabelType::CategoryOnly(
make_label_from_key_and_category(static_key, category),
))
}
(_, _) => {
// Both labels are static and can be validated now
let static_key = self.static_key(key);
let static_category = self.static_category(category);
let name = combine_base_identifier_and_labels(
self.counter.meta().inner.name.as_str(),
static_key,
static_category,
);
self.counter.with_name(name)
}
}
}
/// Creates a static label for the key dimension.
///
/// # Safety
///
/// Should only be called when static labels are available on this metric.
///
/// # Arguments
///
/// * `key` - The requested key
///
/// # Returns
///
/// The requested key if it is in the list of allowed labels.
/// Otherwise `OTHER_LABEL` is returned.
fn static_key<'a>(&self, key: &'a str) -> &'a str {
debug_assert!(self.keys.is_some());
let keys = self.keys.as_ref().unwrap();
if keys.iter().any(|l| l == key) {
key
} else {
OTHER_LABEL
}
}
/// Creates a static label for the category dimension.
///
/// # Safety
///
/// Should only be called when static labels are available on this metric.
///
/// # Arguments
///
/// * `category` - The requested category
///
/// # Returns
///
/// The requested category if it is in the list of allowed labels.
/// Otherwise `OTHER_LABEL` is returned.
fn static_category<'a>(&self, category: &'a str) -> &'a str {
debug_assert!(self.categories.is_some());
let categories = self.categories.as_ref().unwrap();
if categories.iter().any(|l| l == category) {
category
} else {
OTHER_LABEL
}
}
/// Gets a specific metric for a given key/category combination.
///
/// If a set of acceptable labels were specified in the `metrics.yaml` file,
/// and the given label is not in the set, it will be recorded under the special `OTHER_LABEL` label.
///
/// If a set of acceptable labels was not specified in the `metrics.yaml` file,
/// only the first 16 unique labels will be used.
/// After that, any additional labels will be recorded under the special `OTHER_LABEL` label.
///
/// Labels must have a maximum of 111 characters, and may comprise any printable ASCII characters.
/// If an invalid label is used, the metric will be recorded in the special `OTHER_LABEL` label.
pub fn get<S: AsRef<str>>(&self, key: S, category: S) -> Arc<CounterMetric> {
let key = key.as_ref();
let category = category.as_ref();
let mut map = self.dual_label_map.lock().unwrap();
map.entry((key.to_string(), category.to_string()))
.or_insert_with(|| {
let metric = self.new_counter_metric(key, category);
Arc::new(metric)
})
.clone()
}
/// **Exported for test purposes.**
///
/// Gets the number of recorded errors for the given metric and error type.
///
/// # Arguments
///
/// * `error` - The type of error
///
/// # Returns
///
/// The number of errors reported.
pub fn test_get_num_recorded_errors(&self, error: ErrorType) -> i32 {
crate::block_on_dispatcher();
crate::core::with_glean(|glean| {
test_get_num_recorded_errors(glean, self.counter.meta(), error).unwrap_or(0)
})
}
}
/// Combines a metric's base identifier and label
pub fn combine_base_identifier_and_labels(
base_identifer: &str,
key: &str,
category: &str,
) -> String {
format!(
"{}{}",
base_identifer,
make_label_from_key_and_category(key, category)
)
}
/// Separate label into key and category components.
/// Must validate the label format before calling this to ensure it doesn't contain
/// any ASCII record separator characters aside from the one's we put there.
pub fn separate_label_into_key_and_category(label: &str) -> Option<(&str, &str)> {
label
.strip_prefix(RECORD_SEPARATOR)
.unwrap_or(label)
.split_once(RECORD_SEPARATOR)
}
/// Construct and return a label from a given key and category with the RECORD_SEPARATOR
/// characters in the format: <RS><key><RS><category>
pub fn make_label_from_key_and_category(key: &str, category: &str) -> String {
format!(
"{}{}{}{}",
RECORD_SEPARATOR, key, RECORD_SEPARATOR, category
)
}
/// Validates a dynamic label, changing it to `OTHER_LABEL` if it's invalid.
///
/// Checks the requested label against limitations, such as the label length and allowed
/// characters.
///
/// # Arguments
///
/// * `label` - The requested label
///
/// # Returns
///
/// The entire identifier for the metric, including the base identifier and the corrected label.
/// The errors are logged.
pub fn validate_dynamic_key_and_or_category(
glean: &Glean,
meta: &CommonMetricDataInternal,
base_identifier: &str,
label: DynamicLabelType,
) -> String {
// We should have exactly 3 elements when splitting by `RECORD_SEPARATOR`, since the label should begin with one and
// then the key and category are separated by one. Split should contain an empty string, the key, and the category.
// If we have more than 3 elements, then the consuming app must have used this character as part of a label and we
// cannot determine whether it was the key or the category at this point, so we record an `InvalidLabel` error and
// return `OTHER_LABEL` for both key and category.
if label.split(RECORD_SEPARATOR).count() != 3 {
let msg = "Label cannot contain the ASCII record separator character (0x1E)".to_string();
record_error(glean, meta, ErrorType::InvalidLabel, msg, None);
return combine_base_identifier_and_labels(base_identifier, OTHER_LABEL, OTHER_LABEL);
}
// Pick out the key and category from the supplied label
if let Some((mut key, mut category)) = separate_label_into_key_and_category(&label) {
// Loop through the stores we expect to find this metric in, and if we
// find it then just return the full metric identifier that was found
for store in &meta.inner.send_in_pings {
if glean.storage().has_metric(meta.inner.lifetime, store, key) {
return combine_base_identifier_and_labels(base_identifier, key, category);
}
}
// Count the number of distinct keys and categories already recorded, we can figure out which
// one(s) to check based on the label variant.
let (seen_keys, seen_categories) = get_seen_keys_and_categories(meta, glean);
match label {
DynamicLabelType::Label(ref label) => {
record_error(
glean,
meta,
ErrorType::InvalidLabel,
format!("Invalid `DualLabeledCounter` label format: {label:?}"),
None,
);
key = OTHER_LABEL;
category = OTHER_LABEL;
}
DynamicLabelType::KeyOnly(_) => {
if (!seen_keys.contains(key) && seen_keys.len() >= MAX_LABELS)
|| !label_is_valid(key, glean, meta)
{
key = OTHER_LABEL;
}
}
DynamicLabelType::CategoryOnly(_) => {
if (!seen_categories.contains(category) && seen_categories.len() >= MAX_LABELS)
|| !label_is_valid(category, glean, meta)
{
category = OTHER_LABEL;
}
}
DynamicLabelType::KeyAndCategory(_) => {
if (!seen_keys.contains(key) && seen_keys.len() >= MAX_LABELS)
|| !label_is_valid(key, glean, meta)
{
key = OTHER_LABEL;
}
if (!seen_categories.contains(category) && seen_categories.len() >= MAX_LABELS)
|| !label_is_valid(category, glean, meta)
{
category = OTHER_LABEL;
}
}
}
combine_base_identifier_and_labels(base_identifier, key, category)
} else {
record_error(
glean,
meta,
ErrorType::InvalidLabel,
"Invalid `DualLabeledCounter` label format, unable to determine key and/or category",
None,
);
combine_base_identifier_and_labels(base_identifier, OTHER_LABEL, OTHER_LABEL)
}
}
fn label_is_valid(label: &str, glean: &Glean, meta: &CommonMetricDataInternal) -> bool {
if label.len() > MAX_LABEL_LENGTH {
let msg = format!(
"label length {} exceeds maximum of {}",
label.len(),
MAX_LABEL_LENGTH
);
record_error(glean, meta, ErrorType::InvalidLabel, msg, None);
false
} else {
true
}
}
fn get_seen_keys_and_categories(
meta: &CommonMetricDataInternal,
glean: &Glean,
) -> (HashSet<String>, HashSet<String>) {
let base_identifier = &meta.base_identifier();
let prefix = format!("{base_identifier}{RECORD_SEPARATOR}");
let mut seen_keys: HashSet<String> = HashSet::new();
let mut seen_categories: HashSet<String> = HashSet::new();
let mut snapshotter = |metric_id: &[u8], _: &Metric| {
let metric_id_str = String::from_utf8_lossy(metric_id);
// Split full identifier on the ASCII Record Separator (\x1e)
let parts: Vec<&str> = metric_id_str.split(RECORD_SEPARATOR).collect();
if parts.len() == 2 {
seen_keys.insert(parts[0].into());
seen_categories.insert(parts[1].into());
} else {
record_error(
glean,
meta,
ErrorType::InvalidLabel,
"Dual Labeled Counter label doesn't contain exactly 2 parts".to_string(),
None,
);
}
};
let lifetime = meta.inner.lifetime;
for store in &meta.inner.send_in_pings {
glean
.storage()
.iter_store_from(lifetime, store, Some(&prefix), &mut snapshotter);
}
(seen_keys, seen_categories)
}