From d7c0ac92d62cc04b20ae9873c87fd39d16ebf5ab Mon Sep 17 00:00:00 2001 From: Travis Long Date: Thu, 1 Oct 2026 12:06:02 -0500 Subject: [PATCH 1/2] Bug 2077138 - Implement the flow lifecycle and the glean.flow_end event --- docs/user/user/collected-metrics/metrics.md | 1 + glean-core/metrics.yaml | 49 ++ glean-core/src/flows/mod.rs | 528 +++++++++++++++++++- glean-core/src/metrics/event.rs | 42 +- glean-core/tests/metrics_sync.rs | 1 + 5 files changed, 604 insertions(+), 17 deletions(-) diff --git a/docs/user/user/collected-metrics/metrics.md b/docs/user/user/collected-metrics/metrics.md index 469035d65e..17254d6ec5 100644 --- a/docs/user/user/collected-metrics/metrics.md +++ b/docs/user/user/collected-metrics/metrics.md @@ -156,6 +156,7 @@ In addition to those built-in metrics, the following metrics are added to the pi | Name | Type | Description | Data reviews | Extras | Expiration | [Data Sensitivity](https://wiki.mozilla.org/Firefox/Data_Collection) | | --- | --- | --- | --- | --- | --- | --- | +| glean.flow_end |[event](https://mozilla.github.io/glean/book/user/metrics/event.html) |Recorded when a flow instance ends. Every instance records exactly one. Recorded in the session that owns the instance, after the instance's last tagged event, but never carries a `flows` entry itself. Its timestamp is when Glean noticed the instance had ended, which is when it actually ended only for `reason: exit`. |[Review 1](TODO data review), [Bug 2077138](https://bugzilla.mozilla.org/show_bug.cgi?id=2077138)||never |1 | | glean.session_end |[event](https://mozilla.github.io/glean/book/user/metrics/event.html) |Recorded when a session ends. Always emitted regardless of session sampling. The `reason` extra key describes why the session ended. |[Review 1](TODO data review), [Bug 2020962](https://bugzilla.mozilla.org/show_bug.cgi?id=2020962)||never |1 | | glean.session_start |[event](https://mozilla.github.io/glean/book/user/metrics/event.html) |Recorded when a new session starts. Always emitted regardless of session sampling so analysts can observe all session boundaries and validate sampling rates. |[Review 1](TODO data review), [Bug 2020962](https://bugzilla.mozilla.org/show_bug.cgi?id=2020962)||never |1 | diff --git a/glean-core/metrics.yaml b/glean-core/metrics.yaml index dd33b7db69..df27d11733 100644 --- a/glean-core/metrics.yaml +++ b/glean-core/metrics.yaml @@ -1183,6 +1183,55 @@ glean: - "abnormal_inactive": session was inactive at time of crash type: string + flow_end: + type: event + description: | + Recorded when a flow instance ends. Every instance records exactly one. + + Recorded in the session that owns the instance, after the instance's last + tagged event, but never carries a `flows` entry itself. Its timestamp is + when Glean noticed the instance had ended, which is when it actually ended + only for `reason: exit`. + send_in_pings: + - events + bugs: + - https://bugzilla.mozilla.org/show_bug.cgi?id=2077138 + data_reviews: + - "TODO data review" + - https://bugzilla.mozilla.org/show_bug.cgi?id=2077138 + data_sensitivity: + - technical + notification_emails: + - glean-team@mozilla.com + expires: never + extra_keys: + flow_name: + description: The name of the flow, as declared in `flows.yaml`. + type: string + flow_seq: + description: | + The instance's sequence number within its session. Matches `seq` in + the `flows` entries of the instance's tagged events. + type: quantity + reason: + description: | + Why the instance ended: + - "exit": an event in the flow's `ends_on` was recorded + - "timeout": the flow's `auto_close_timeout` elapsed + - "session_end": the session ended while the instance was active + - "abnormal": the app ended abnormally while the instance was active + type: string + terminating_event: + description: | + The event that closed the instance (`category.name`). Only present + when `reason` is "exit". + type: string + session_id: + description: | + The session that owned the instance. Only present when `reason` is + "abnormal", since that `flow_end` is recorded outside any session. + type: string + sessions_seen: type: counter description: | diff --git a/glean-core/src/flows/mod.rs b/glean-core/src/flows/mod.rs index ed209e9f1c..715a817664 100644 --- a/glean-core/src/flows/mod.rs +++ b/glean-core/src/flows/mod.rs @@ -10,13 +10,16 @@ //! definitions into a [`FlowRegistry`], keyed by event, so the recording path //! resolves everything it needs about an event with a single lookup. +use std::collections::btree_map::Entry; use std::collections::{BTreeMap, HashMap}; +use chrono::Utc; use malloc_size_of_derive::MallocSizeOf; use serde::{Deserialize, Serialize}; use crate::common_metric_data::CommonMetricDataInternal; -use crate::Glean; +use crate::session::EventSessionContext; +use crate::{CommonMetricData, Glean, Lifetime}; /// The role an event plays in a flow. #[derive(Debug, Clone, Copy, PartialEq, Eq, MallocSizeOf)] @@ -190,15 +193,88 @@ impl FlowRegistry { pub(crate) struct FlowState { /// Each active flow, mapped to its instance's `flow_seq`. pub(crate) active: BTreeMap, + /// The `flow_seq` the next instance opened in this session will get. + pub(crate) next_seq: u64, +} + +impl FlowState { + /// Opens an instance of `flow`, unless one is already active. + /// + /// An entry event recorded while its flow is active does nothing: the + /// active instance is kept, not replaced. + fn open(&mut self, flow: FlowId) { + if let Entry::Vacant(entry) = self.active.entry(flow) { + entry.insert(self.next_seq); + self.next_seq += 1; + } + } +} + +/// Why a flow instance ended, as reported in `glean.flow_end`. +// TODO(bugs 2077139, 2077141, 2077143): the session-end, timeout, and +// persistence bugs construct the remaining reasons. +#[allow(dead_code)] +#[derive(Debug, Clone, Copy)] +pub(crate) enum FlowEndReason<'a> { + /// An event in the flow's `ends_on` was recorded. + Exit { + /// The closing event's identifier (`category.name`). + terminating_event: &'a str, + }, + /// The flow's `auto_close_timeout` elapsed. + Timeout, + /// The session ended while the instance was active. + SessionEnd, + /// The app ended abnormally while the instance was active. + Abnormal { + /// The session that owned the instance. + session_id: &'a str, + }, +} + +impl FlowEndReason<'_> { + fn as_str(&self) -> &'static str { + match self { + FlowEndReason::Exit { .. } => "exit", + FlowEndReason::Timeout => "timeout", + FlowEndReason::SessionEnd => "session_end", + FlowEndReason::Abnormal { .. } => "abnormal", + } + } +} + +/// Looks up the flows an event metric's recording can affect. +/// +/// Returns `None` unless the metric is in-session and a session is active, +/// since instances only exist within a session: an event recorded between +/// sessions neither opens an instance nor is tagged. +pub(crate) fn lookup<'a>( + glean: &'a Glean, + meta: &CommonMetricDataInternal, +) -> Option<&'a EventFlows> { + if !meta.inner.in_session || !glean.session_manager().is_active() { + return None; + } + glean.flow_registry.lookup_metric(meta) +} + +/// Opens an instance of every flow the event starts that has none active. +/// +/// Nothing is recorded: the entry event itself is tagged with the new instance. +pub(crate) fn open_instances(glean: &Glean, event_flows: &EventFlows) { + if event_flows.starts.is_empty() { + return; + } + let mut state = glean.flow_state.lock().unwrap(); + for flow in &event_flows.starts { + state.open(*flow); + } } /// Returns a `flows` entry for every active instance of a flow the event belongs to. /// /// Entries are in name order, which `member_of` already is. -pub(crate) fn active_entries(glean: &Glean, meta: &CommonMetricDataInternal) -> Vec { - let Some(event_flows) = glean.flow_registry.lookup_metric(meta) else { - return Vec::new(); - }; +pub(crate) fn active_entries(glean: &Glean, event_flows: &EventFlows) -> Vec { let state = glean.flow_state.lock().unwrap(); event_flows .member_of @@ -212,6 +288,110 @@ pub(crate) fn active_entries(glean: &Glean, meta: &CommonMetricDataInternal) -> .collect() } +/// Closes the active instance of every flow the event ends, recording a +/// `glean.flow_end` with `reason: exit` for each. +/// +/// Must be called after the event itself is recorded, so each `flow_end` gets +/// a higher `session.event_seq` than the event that closed it. +/// +/// Returns `true` if any `flow_end` caused a ping to be submitted. +pub(crate) fn close_instances( + glean: &Glean, + event_flows: &EventFlows, + meta: &CommonMetricDataInternal, +) -> bool { + if event_flows.ends.is_empty() { + return false; + } + let closed: Vec<(FlowId, u64)> = { + let mut state = glean.flow_state.lock().unwrap(); + event_flows + .ends + .iter() + .filter_map(|flow| state.active.remove(flow).map(|seq| (*flow, seq))) + .collect() + }; + if closed.is_empty() { + return false; + } + + let terminating_event = meta.base_identifier(); + let mut submitted = false; + for (flow, seq) in closed { + submitted |= record_flow_end( + glean, + &glean.flow_registry.flow(flow).name, + seq, + FlowEndReason::Exit { + terminating_event: &terminating_event, + }, + ); + } + submitted +} + +/// Records a `glean.flow_end` event. +/// +/// Like `glean.session_end`, this bypasses `EventMetric` and records directly, +/// but in-session rather than out-of-session, so it is ordered against the +/// instance's own events by `session.event_seq`. It is never flow-tagged. The +/// exception is `reason: abnormal`, recorded at startup before any session +/// exists, which carries the owning session's ID as an extra instead. +/// +/// Returns `true` if recording it caused a ping to be submitted. +pub(crate) fn record_flow_end( + glean: &Glean, + flow_name: &str, + flow_seq: u64, + reason: FlowEndReason, +) -> bool { + let meta = CommonMetricData { + name: "flow_end".into(), + category: "glean".into(), + send_in_pings: vec!["events".into()], + lifetime: Lifetime::Ping, + ..Default::default() + }; + + let mut extra = HashMap::new(); + extra.insert("flow_name".to_string(), flow_name.to_string()); + extra.insert("flow_seq".to_string(), flow_seq.to_string()); + extra.insert("reason".to_string(), reason.as_str().to_string()); + let ctx = match reason { + FlowEndReason::Exit { terminating_event } => { + extra.insert( + "terminating_event".to_string(), + terminating_event.to_string(), + ); + glean.session_manager().compute_event_context() + } + FlowEndReason::Abnormal { session_id } => { + extra.insert("session_id".to_string(), session_id.to_string()); + EventSessionContext::OutOfSession + } + FlowEndReason::Timeout | FlowEndReason::SessionEnd => { + glean.session_manager().compute_event_context() + } + }; + // Wall-clock time, matching `EventMetric::record`. The event's main + // timestamp stays on the monotonic clock. + if glean.with_timestamps() { + extra.insert( + "glean_timestamp".to_string(), + Utc::now().timestamp_millis().to_string(), + ); + } + + glean.event_storage().record( + glean, + &meta.into(), + crate::get_timestamp_ms(), + Some(extra), + ctx, + Vec::new(), + ) +} + #[cfg(test)] mod test { use super::*; @@ -323,7 +503,12 @@ mod test { fn glean_with_flows(flows: Vec) -> (Glean, tempfile::TempDir) { let dir = tempfile::tempdir().unwrap(); - let cfg = InternalConfiguration { + let cfg = test_cfg(&dir, flows); + (Glean::new(cfg).unwrap(), dir) + } + + fn test_cfg(dir: &tempfile::TempDir, flows: Vec) -> InternalConfiguration { + InternalConfiguration { data_path: dir.path().display().to_string(), application_id: "org.mozilla.glean.test.app".into(), language_binding_name: "Rust".into(), @@ -349,8 +534,7 @@ mod test { events_ping_acceleration_factor: None, enable_store_submitted_pings: false, flows, - }; - (Glean::new(cfg).unwrap(), dir) + } } fn event(category: &str, name: &str, in_session: bool) -> EventMetric { @@ -508,4 +692,332 @@ mod test { .unwrap(); assert!(event.flows.is_empty()); } + + // ----------------------------------------------------------------------- + // Lifecycle + // ----------------------------------------------------------------------- + + /// The `onboarding` flow from the proposal's worked example. + fn onboarding() -> FlowDefinition { + definition( + "onboarding", + &[ + ("onboarding.started", FlowRole::Start), + ("onboarding.finished", FlowRole::End), + ("onboarding.dismissed", FlowRole::End), + ("onboarding.card_shown", FlowRole::Member), + ("onboarding.permission_prompted", FlowRole::Member), + ], + ) + } + + fn flow_end_metric() -> EventMetric { + EventMetric::new( + CommonMetricData { + category: "glean".into(), + name: "flow_end".into(), + send_in_pings: vec!["events".into()], + lifetime: Lifetime::Ping, + ..Default::default() + }, + vec![], + ) + } + + fn flow_ends(glean: &Glean) -> Vec> { + flow_end_metric() + .get_value(glean, "events") + .unwrap_or_default() + .into_iter() + .map(|e| e.extra.unwrap()) + .collect() + } + + fn exit_extras(flow: &str, seq: u64, terminating_event: &str) -> HashMap { + [ + ("flow_name", flow.to_string()), + ("flow_seq", seq.to_string()), + ("reason", "exit".to_string()), + ("terminating_event", terminating_event.to_string()), + ] + .into_iter() + .map(|(k, v)| (k.to_string(), v)) + .collect() + } + + fn record(glean: &Glean, category: &str, name: &str) -> bool { + event(category, name, true).record_sync(glean, 0, HashMap::new(), 0) + } + + /// The worked example from the proposal, row by row. + #[test] + fn worked_example() { + let (mut glean, _t) = glean_with_flows(vec![onboarding()]); + + glean.session_start(); + let steps = [ + ("onboarding", "started"), + ("onboarding", "card_shown"), + ("onboarding", "permission_prompted"), + ("settings", "opened"), + ("onboarding", "card_shown"), + ("onboarding", "dismissed"), + ]; + // The snapshot is ordered by timestamp, so use the same clock as the + // session boundary events. + for (category, name) in steps { + event(category, name, true).record_sync( + &glean, + crate::get_timestamp_ms(), + HashMap::new(), + 0, + ); + } + glean.session_end(None); + + let json = glean + .event_storage() + .snapshot_as_json(&glean, "events", false) + .unwrap(); + let rows: Vec<(String, Option, serde_json::Value)> = json + .as_array() + .unwrap() + .iter() + .map(|e| { + ( + format!( + "{}.{}", + e["category"].as_str().unwrap(), + e["name"].as_str().unwrap() + ), + e["session"]["event_seq"].as_u64(), + e.get("flows").cloned().unwrap_or(serde_json::Value::Null), + ) + }) + .collect(); + + let tagged = serde_json::json!([{"name": "onboarding", "seq": 0}]); + let none = serde_json::Value::Null; + let expected = vec![ + ("glean.session_start", None, none.clone()), + ("onboarding.started", Some(0), tagged.clone()), + ("onboarding.card_shown", Some(1), tagged.clone()), + ("onboarding.permission_prompted", Some(2), tagged.clone()), + ("settings.opened", Some(3), none.clone()), + ("onboarding.card_shown", Some(4), tagged.clone()), + ("onboarding.dismissed", Some(5), tagged.clone()), + ("glean.flow_end", Some(6), none.clone()), + ("glean.session_end", None, none), + ]; + let expected: Vec<(String, Option, serde_json::Value)> = expected + .into_iter() + .map(|(name, seq, flows)| (name.to_string(), seq, flows)) + .collect(); + assert_eq!(expected, rows); + + assert_eq!( + vec![exit_extras("onboarding", 0, "onboarding.dismissed")], + flow_ends(&glean) + ); + } + + #[test] + fn entry_event_while_active_keeps_the_existing_instance() { + let (mut glean, _t) = glean_with_flows(vec![onboarding()]); + glean.session_start(); + + record(&glean, "onboarding", "started"); + record(&glean, "onboarding", "started"); + record(&glean, "onboarding", "dismissed"); + + let starts = event("onboarding", "started", true) + .get_value(&glean, "events") + .unwrap(); + assert_eq!(vec![entry("onboarding", 0)], starts[0].flows); + assert_eq!(vec![entry("onboarding", 0)], starts[1].flows); + assert_eq!( + vec![exit_extras("onboarding", 0, "onboarding.dismissed")], + flow_ends(&glean) + ); + } + + #[test] + fn exit_event_while_inactive_does_nothing() { + let (mut glean, _t) = glean_with_flows(vec![onboarding()]); + glean.session_start(); + + record(&glean, "onboarding", "dismissed"); + + let dismissed = event("onboarding", "dismissed", true) + .get_value(&glean, "events") + .unwrap(); + assert!(dismissed[0].flows.is_empty()); + assert!(flow_ends(&glean).is_empty()); + } + + #[test] + fn second_attempt_in_a_session_is_a_new_instance() { + let (mut glean, _t) = glean_with_flows(vec![onboarding()]); + glean.session_start(); + + record(&glean, "onboarding", "started"); + record(&glean, "onboarding", "dismissed"); + record(&glean, "onboarding", "started"); + record(&glean, "onboarding", "card_shown"); + record(&glean, "onboarding", "finished"); + + let shown = event("onboarding", "card_shown", true) + .get_value(&glean, "events") + .unwrap(); + assert_eq!(vec![entry("onboarding", 1)], shown[0].flows); + assert_eq!( + vec![ + exit_extras("onboarding", 0, "onboarding.dismissed"), + exit_extras("onboarding", 1, "onboarding.finished"), + ], + flow_ends(&glean) + ); + } + + #[test] + fn no_instance_opens_without_an_active_session() { + let (glean, _t) = glean_with_flows(vec![onboarding()]); + + record(&glean, "onboarding", "started"); + + assert!(glean.flow_state.lock().unwrap().active.is_empty()); + } + + #[test] + fn a_suppressed_entry_event_opens_nothing() { + let (mut glean, _t) = glean_with_flows(vec![onboarding()]); + glean.session_start(); + + let disabled = EventMetric::new( + CommonMetricData { + category: "onboarding".into(), + name: "started".into(), + send_in_pings: vec!["events".into()], + lifetime: Lifetime::Ping, + in_session: true, + disabled: true, + ..Default::default() + }, + vec![], + ); + disabled.record_sync(&glean, 0, HashMap::new(), 0); + + assert!(glean.flow_state.lock().unwrap().active.is_empty()); + } + + #[test] + fn one_event_can_end_one_flow_and_start_another() { + let (mut glean, _t) = glean_with_flows(vec![ + definition( + "browse", + &[ + ("browse.started", FlowRole::Start), + ("checkout.started", FlowRole::End), + ], + ), + definition( + "checkout", + &[ + ("checkout.started", FlowRole::Start), + ("checkout.paid", FlowRole::End), + ], + ), + ]); + glean.session_start(); + + record(&glean, "browse", "started"); + record(&glean, "checkout", "started"); + + let started = event("checkout", "started", true) + .get_value(&glean, "events") + .unwrap(); + // Tagged with both: the instance it closes and the one it opens. + assert_eq!( + vec![entry("browse", 0), entry("checkout", 1)], + started[0].flows + ); + assert_eq!( + vec![exit_extras("browse", 0, "checkout.started")], + flow_ends(&glean) + ); + let checkout = glean.flow_registry.find("checkout").unwrap(); + assert_eq!( + Some(&1), + glean.flow_state.lock().unwrap().active.get(&checkout) + ); + } + + #[test] + fn event_ending_two_flows_records_a_flow_end_for_each_in_name_order() { + let shared_exit = ("app.closed", FlowRole::End); + let (mut glean, _t) = glean_with_flows(vec![ + definition("zeta", &[("zeta.started", FlowRole::Start), shared_exit]), + definition("alpha", &[("alpha.started", FlowRole::Start), shared_exit]), + ]); + glean.session_start(); + + record(&glean, "zeta", "started"); + record(&glean, "alpha", "started"); + record(&glean, "app", "closed"); + + assert_eq!( + vec![ + exit_extras("alpha", 1, "app.closed"), + exit_extras("zeta", 0, "app.closed"), + ], + flow_ends(&glean) + ); + } + + #[test] + fn flow_end_carries_a_wall_clock_glean_timestamp() { + let dir = tempfile::tempdir().unwrap(); + let mut cfg = test_cfg(&dir, vec![onboarding()]); + cfg.enable_event_timestamps = true; + let mut glean = Glean::new(cfg).unwrap(); + glean.session_start(); + + let before = Utc::now().timestamp_millis(); + record(&glean, "onboarding", "started"); + record(&glean, "onboarding", "dismissed"); + let after = Utc::now().timestamp_millis(); + + let json = glean + .event_storage() + .snapshot_as_json(&glean, "events", false) + .unwrap(); + let flow_end = json + .as_array() + .unwrap() + .iter() + .find(|e| e["category"] == "glean" && e["name"] == "flow_end") + .unwrap(); + let glean_timestamp: i64 = flow_end["extra"]["glean_timestamp"] + .as_str() + .unwrap() + .parse() + .unwrap(); + assert!((before..=after).contains(&glean_timestamp)); + } + + #[test] + fn ping_submitted_by_flow_end_is_reported_to_the_caller() { + let dir = tempfile::tempdir().unwrap(); + let mut cfg = test_cfg(&dir, vec![onboarding()]); + // session_start, started, dismissed, and then flow_end fills the store. + cfg.max_events = Some(4); + let mut glean = Glean::new(cfg).unwrap(); + glean.session_start(); + + assert!(!record(&glean, "onboarding", "started")); + assert!( + record(&glean, "onboarding", "dismissed"), + "the ping submitted by flow_end must be reported by the exit event's recording" + ); + } } diff --git a/glean-core/src/metrics/event.rs b/glean-core/src/metrics/event.rs index 72f04bf5c6..2c6a1f9ab0 100644 --- a/glean-core/src/metrics/event.rs +++ b/glean-core/src/metrics/event.rs @@ -7,6 +7,7 @@ use std::collections::HashMap; use crate::common_metric_data::CommonMetricDataInternal; use crate::error_recording::{record_error, test_get_num_recorded_errors, ErrorType}; use crate::event_database::RecordedEvent; +use crate::flows; use crate::metrics::MetricType; use crate::session::EventSessionContext; use crate::util::truncate_string_at_boundary_with_error; @@ -170,16 +171,39 @@ impl EventMetric { EventSessionContext::OutOfSession }; - // Flow instances only exist within a session, so an out-of-session event - // is never tagged, even if a flow names it. - let flows = match &ctx { - EventSessionContext::InSession(_) => crate::flows::active_entries(glean, &self.meta), - EventSessionContext::OutOfSession => Vec::new(), - }; + // Flow boundaries are handled while this event is recorded. Coming after + // `should_record()` and extra validation, an event that isn't recorded + // never opens or closes an instance. + let event_flows = flows::lookup(glean, &self.meta); - glean - .event_storage() - .record(glean, &self.meta, timestamp, extra_strings, ctx, flows) + // 1. Open any instance this event starts, so it is tagged with it below. + if let Some(event_flows) = event_flows { + flows::open_instances(glean, event_flows); + } + + // 2. Tag the event with every active instance it belongs to. Computed + // before step 4, so an exit event is tagged with the instance it closes. + let flow_entries = event_flows + .map(|event_flows| flows::active_entries(glean, event_flows)) + .unwrap_or_default(); + + // 3. Record the event. + let mut submitted = glean.event_storage().record( + glean, + &self.meta, + timestamp, + extra_strings, + ctx, + flow_entries, + ); + + // 4. Close any instance this event ends, recording `glean.flow_end` after + // the event so it takes the higher `session.event_seq`. + if let Some(event_flows) = event_flows { + submitted |= flows::close_instances(glean, event_flows, &self.meta); + } + + submitted } /// **Test-only API (exported for FFI purposes).** diff --git a/glean-core/tests/metrics_sync.rs b/glean-core/tests/metrics_sync.rs index 3ae958cad8..800f71a13a 100644 --- a/glean-core/tests/metrics_sync.rs +++ b/glean-core/tests/metrics_sync.rs @@ -25,6 +25,7 @@ static DEFINITION_ONLY: &[&str] = &[ /* adhoc in src/ping/mod.rs */ "glean.ping.uploader_capabilities", /* adhoc events */ + "glean.flow_end", "glean.restarted", "glean.session_end", "glean.session_start", From f010325aad0566d160efa09312ccc905cd78818a Mon Sep 17 00:00:00 2001 From: Travis Long Date: Wed, 18 Nov 2026 06:07:14 -0600 Subject: [PATCH 2/2] Bug 2077138 - Address review feedback on the flow lifecycle - Take the EventMetric itself in flows::lookup and close_instances, so only an event's recording can affect flows, enforced by the type system. - Build the glean.flow_end metadata once in a static rather than per call. - Reuse Glean::maybe_inject_glean_timestamp instead of duplicating it. - Reword the FlowState::open doc to avoid talking about events. --- glean-core/src/core/mod.rs | 5 ++- glean-core/src/flows/mod.rs | 55 +++++++++++++++++---------------- glean-core/src/metrics/event.rs | 4 +-- 3 files changed, 34 insertions(+), 30 deletions(-) diff --git a/glean-core/src/core/mod.rs b/glean-core/src/core/mod.rs index e395473666..d37fc4b1e2 100644 --- a/glean-core/src/core/mod.rs +++ b/glean-core/src/core/mod.rs @@ -1580,7 +1580,10 @@ impl Glean { /// /// Uses the wall clock, matching `EventMetric::record`. The event's main /// `timestamp` stays on the monotonic clock. - fn maybe_inject_glean_timestamp(&self, extra: &mut std::collections::HashMap) { + pub(crate) fn maybe_inject_glean_timestamp( + &self, + extra: &mut std::collections::HashMap, + ) { if self.with_timestamps { let precise_timestamp = Utc::now().timestamp_millis() as u64; extra.insert("glean_timestamp".to_string(), precise_timestamp.to_string()); diff --git a/glean-core/src/flows/mod.rs b/glean-core/src/flows/mod.rs index 715a817664..db6e24ead3 100644 --- a/glean-core/src/flows/mod.rs +++ b/glean-core/src/flows/mod.rs @@ -13,11 +13,12 @@ use std::collections::btree_map::Entry; use std::collections::{BTreeMap, HashMap}; -use chrono::Utc; use malloc_size_of_derive::MallocSizeOf; +use once_cell::sync::Lazy; use serde::{Deserialize, Serialize}; use crate::common_metric_data::CommonMetricDataInternal; +use crate::metrics::{EventMetric, MetricType}; use crate::session::EventSessionContext; use crate::{CommonMetricData, Glean, Lifetime}; @@ -200,8 +201,8 @@ pub(crate) struct FlowState { impl FlowState { /// Opens an instance of `flow`, unless one is already active. /// - /// An entry event recorded while its flow is active does nothing: the - /// active instance is kept, not replaced. + /// Opening an already-open flow does nothing: the existing active + /// instance is kept, not replaced. fn open(&mut self, flow: FlowId) { if let Entry::Vacant(entry) = self.active.entry(flow) { entry.insert(self.next_seq); @@ -245,13 +246,15 @@ impl FlowEndReason<'_> { /// Looks up the flows an event metric's recording can affect. /// +/// Takes the `EventMetric` itself, rather than its metadata, because flows are +/// built from events: `in_session` is not limited to event metrics, but only +/// an event's recording may open, tag, or close an instance. +/// /// Returns `None` unless the metric is in-session and a session is active, /// since instances only exist within a session: an event recorded between /// sessions neither opens an instance nor is tagged. -pub(crate) fn lookup<'a>( - glean: &'a Glean, - meta: &CommonMetricDataInternal, -) -> Option<&'a EventFlows> { +pub(crate) fn lookup<'a>(glean: &'a Glean, metric: &EventMetric) -> Option<&'a EventFlows> { + let meta = metric.meta(); if !meta.inner.in_session || !glean.session_manager().is_active() { return None; } @@ -298,7 +301,7 @@ pub(crate) fn active_entries(glean: &Glean, event_flows: &EventFlows) -> Vec bool { if event_flows.ends.is_empty() { return false; @@ -315,7 +318,7 @@ pub(crate) fn close_instances( return false; } - let terminating_event = meta.base_identifier(); + let terminating_event = metric.meta().base_identifier(); let mut submitted = false; for (flow, seq) in closed { submitted |= record_flow_end( @@ -330,6 +333,19 @@ pub(crate) fn close_instances( submitted } +/// The metadata `glean.flow_end` is recorded with, built once rather than on +/// every call, since a session ending can close many instances at once. +static FLOW_END_META: Lazy = Lazy::new(|| { + CommonMetricData { + name: "flow_end".into(), + category: "glean".into(), + send_in_pings: vec!["events".into()], + lifetime: Lifetime::Ping, + ..Default::default() + } + .into() +}); + /// Records a `glean.flow_end` event. /// /// Like `glean.session_end`, this bypasses `EventMetric` and records directly, @@ -345,14 +361,6 @@ pub(crate) fn record_flow_end( flow_seq: u64, reason: FlowEndReason, ) -> bool { - let meta = CommonMetricData { - name: "flow_end".into(), - category: "glean".into(), - send_in_pings: vec!["events".into()], - lifetime: Lifetime::Ping, - ..Default::default() - }; - let mut extra = HashMap::new(); extra.insert("flow_name".to_string(), flow_name.to_string()); extra.insert("flow_seq".to_string(), flow_seq.to_string()); @@ -373,18 +381,11 @@ pub(crate) fn record_flow_end( glean.session_manager().compute_event_context() } }; - // Wall-clock time, matching `EventMetric::record`. The event's main - // timestamp stays on the monotonic clock. - if glean.with_timestamps() { - extra.insert( - "glean_timestamp".to_string(), - Utc::now().timestamp_millis().to_string(), - ); - } + glean.maybe_inject_glean_timestamp(&mut extra); glean.event_storage().record( glean, - &meta.into(), + &FLOW_END_META, crate::get_timestamp_ms(), Some(extra), ctx, @@ -395,9 +396,9 @@ pub(crate) fn record_flow_end( #[cfg(test)] mod test { use super::*; - use crate::metrics::EventMetric; use crate::session::SessionMode; use crate::{CommonMetricData, InternalConfiguration, Lifetime}; + use chrono::Utc; fn definition(name: &str, events: &[(&str, FlowRole)]) -> FlowDefinition { FlowDefinition { diff --git a/glean-core/src/metrics/event.rs b/glean-core/src/metrics/event.rs index 2c6a1f9ab0..587fa510c6 100644 --- a/glean-core/src/metrics/event.rs +++ b/glean-core/src/metrics/event.rs @@ -174,7 +174,7 @@ impl EventMetric { // Flow boundaries are handled while this event is recorded. Coming after // `should_record()` and extra validation, an event that isn't recorded // never opens or closes an instance. - let event_flows = flows::lookup(glean, &self.meta); + let event_flows = flows::lookup(glean, self); // 1. Open any instance this event starts, so it is tagged with it below. if let Some(event_flows) = event_flows { @@ -200,7 +200,7 @@ impl EventMetric { // 4. Close any instance this event ends, recording `glean.flow_end` after // the event so it takes the higher `session.event_seq`. if let Some(event_flows) = event_flows { - submitted |= flows::close_instances(glean, event_flows, &self.meta); + submitted |= flows::close_instances(glean, event_flows, self); } submitted