Clamp event timestamps to i64::MAX

BigQuery's integer type is a signed 64-bit value, while we collect
unsigned ones.
Timestamps are in milliseconds, so 9223372036854775807 (i64::MAX) ms is
about 4.5 billion years, or roughly 1/15 of the age of earth.
I think we should be fine with that for a little while longer.

So any such value _should_ not happen. But it does in 0.002% of pings
and thus data ends up in `additional_properties` instead of where it
belongs.
By clamping we might reduce that %age further. An event with that
timestamp is most likely still not useful, but maybe the others are?

One more problem is: Should we report this as an issue? If so how? Right
now we don't have the APIs to tie that back to a specific event other
then the one we own. But then our error types don't express the right
things.

Author: badboy

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 [Full changelog](https://github.com/mozilla/glean/compare/v66.3.0...main)
 
+* General
+  * Event timestamps are now always clamped to the range of a signed 64-bit integer.
+    An overflow is recorded in the new metric `glean.error.event_timestamp_clamped` in case this happens ([#3308](https://github.com/mozilla/glean/pull/3308)).
+
 # v66.3.0 (2025-12-19)
 
 [Full changelog](https://github.com/mozilla/glean/compare/v66.2.0...v66.3.0)

glean-core/metrics.yaml

@@ -649,6 +649,24 @@ glean.error:
       - [email protected]
     expires: never
 
+  event_timestamp_clamped:
+    type: counter
+    description: |
+      The number of times we had to clamp an event timestamp
+      for exceeding the range of a signed 64-bit integer (9223372036854775807).
+    send_in_pings:
+      - health
+    bugs:
+      - https://bugzilla.mozilla.org/show_bug.cgi?id=1873482
+    data_reviews:
+      - https://bugzilla.mozilla.org/show_bug.cgi?id=1873482
+    data_sensitivity:
+      - technical
+    notification_emails:
+      - [email protected]
+      - [email protected]
+    expires: 2026-06-31
+
 glean.upload:
   ping_upload_failure:
     type: labeled_counter

glean-core/src/event_database/mod.rs

@@ -560,6 +560,22 @@ impl EventDatabase {
                 // Let's fix cur_ec up and hope this isn't a sign something big is broken.
                 cur_ec = execution_counter;
             }
+
+            // event timestamp is a `u64`, but BigQuery uses `i64` (signed!) everywhere. Let's clamp the value to make
+            // sure we stay within bounds.
+            if event.event.timestamp > i64::MAX as u64 {
+                glean
+                    .additional_metrics
+                    .event_timestamp_clamped
+                    .add_sync(glean, 1);
+                log::warn!(
+                    "Calculated event timestamp was too high. Got: {}, max: {}",
+                    event.event.timestamp,
+                    i64::MAX,
+                );
+                event.event.timestamp = event.event.timestamp.clamp(0, i64::MAX as u64);
+            }
+
             if highest_ts > event.event.timestamp {
                 // Even though we sorted everything, something in the
                 // execution_counter or glean.startup.date math went awry.
@@ -1357,4 +1373,50 @@ mod test {
         )
         .is_err());
     }
+
+    #[test]
+    fn normalize_store_clamps_timestamp() {
+        let (glean, _dir) = new_glean(None);
+
+        let store_name = "store-name";
+        let event = RecordedEvent {
+            category: "category".into(),
+            name: "name".into(),
+            ..Default::default()
+        };
+
+        let timestamps = [
+            0,
+            (i64::MAX / 2) as u64,
+            i64::MAX as _,
+            (i64::MAX as u64) + 1,
+        ];
+        let mut store = timestamps
+            .into_iter()
+            .map(|timestamp| StoredEvent {
+                event: RecordedEvent {
+                    timestamp,
+                    ..event.clone()
+                },
+                execution_counter: None,
+            })
+            .collect();
+
+        let glean_start_time = glean.start_time();
+        glean
+            .event_storage()
+            .normalize_store(&glean, store_name, &mut store, glean_start_time);
+        assert_eq!(4, store.len());
+
+        assert_eq!(0, store[0].event.timestamp);
+        assert_eq!((i64::MAX / 2) as u64, store[1].event.timestamp);
+        assert_eq!((i64::MAX as u64), store[2].event.timestamp);
+        assert_eq!((i64::MAX as u64), store[3].event.timestamp);
+
+        let error_count = glean
+            .additional_metrics
+            .event_timestamp_clamped
+            .get_value(&glean, "health");
+        assert_eq!(Some(1), error_count);
+    }
 }

glean-core/src/internal_metrics.rs

@@ -40,6 +40,10 @@ pub struct AdditionalMetrics {
     /// An experimentation identifier derived and provided by the application
     /// for the purpose of experimentation enrollment.
     pub experimentation_id: StringMetric,
+
+    /// The number of times we had to clamp an event timestamp
+    /// for exceeding the range of a signed 64-bit integer (9223372036854775807).
+    pub event_timestamp_clamped: CounterMetric,
 }
 
 impl CoreMetrics {
@@ -198,6 +202,15 @@ impl AdditionalMetrics {
                 disabled: false,
                 dynamic_label: None,
             }),
+
+            event_timestamp_clamped: CounterMetric::new(CommonMetricData {
+                name: "event_timestamp_clamped".into(),
+                category: "glean.error".into(),
+                send_in_pings: vec!["health".into()],
+                lifetime: Lifetime::Ping,
+                disabled: false,
+                dynamic_label: None,
+            }),
         }
     }
 }