Line data    Source code

       1              : use std::time::SystemTime;
       2              : 
       3              : /// Pageserver current utilization and scoring for how good candidate the pageserver would be for
       4              : /// the next tenant.
       5              : ///
       6              : /// See and maintain pageserver openapi spec for `/v1/utilization_score` as the truth.
       7              : ///
       8              : /// `format: int64` fields must use `ser_saturating_u63` because openapi generated clients might
       9              : /// not handle full u64 values properly.
      10            2 : #[derive(serde::Serialize, Debug)]
      11              : pub struct PageserverUtilization {
      12              :     /// Used disk space
      13              :     #[serde(serialize_with = "ser_saturating_u63")]
      14              :     pub disk_usage_bytes: u64,
      15              :     /// Free disk space
      16              :     #[serde(serialize_with = "ser_saturating_u63")]
      17              :     pub free_space_bytes: u64,
      18              :     /// Lower is better score for how good candidate for a next tenant would this pageserver be.
      19              :     #[serde(serialize_with = "ser_saturating_u63")]
      20              :     pub utilization_score: u64,
      21              :     /// When was this snapshot captured, pageserver local time.
      22              :     ///
      23              :     /// Use millis to give confidence that the value is regenerated often enough.
      24              :     #[serde(serialize_with = "ser_rfc3339_millis")]
      25              :     pub captured_at: SystemTime,
      26              : }
      27              : 
      28            2 : fn ser_rfc3339_millis<S: serde::Serializer>(
      29            2 :     ts: &SystemTime,
      30            2 :     serializer: S,
      31            2 : ) -> Result<S::Ok, S::Error> {
      32            2 :     serializer.collect_str(&humantime::format_rfc3339_millis(*ts))
      33            2 : }
      34              : 
      35              : /// openapi knows only `format: int64`, so avoid outputting a non-parseable value by generated clients.
      36              : ///
      37              : /// Instead of newtype, use this because a newtype would get require handling deserializing values
      38              : /// with the highest bit set which is properly parsed by serde formats, but would create a
      39              : /// conundrum on how to handle and again serialize such values at type level. It will be a few
      40              : /// years until we can use more than `i64::MAX` bytes on a disk.
      41            6 : fn ser_saturating_u63<S: serde::Serializer>(value: &u64, serializer: S) -> Result<S::Ok, S::Error> {
      42            6 :     const MAX_FORMAT_INT64: u64 = i64::MAX as u64;
      43            6 : 
      44            6 :     let value = (*value).min(MAX_FORMAT_INT64);
      45            6 : 
      46            6 :     serializer.serialize_u64(value)
      47            6 : }
      48              : 
      49              : #[cfg(test)]
      50              : mod tests {
      51              :     use std::time::Duration;
      52              : 
      53              :     use super::*;
      54              : 
      55            2 :     #[test]
      56            2 :     fn u64_max_is_serialized_as_u63_max() {
      57            2 :         let doc = PageserverUtilization {
      58            2 :             disk_usage_bytes: u64::MAX,
      59            2 :             free_space_bytes: 0,
      60            2 :             utilization_score: u64::MAX,
      61            2 :             captured_at: SystemTime::UNIX_EPOCH + Duration::from_secs(1708509779),
      62            2 :         };
      63            2 : 
      64            2 :         let s = serde_json::to_string(&doc).unwrap();
      65            2 : 
      66            2 :         let expected = r#"{"disk_usage_bytes":9223372036854775807,"free_space_bytes":0,"utilization_score":9223372036854775807,"captured_at":"2024-02-21T10:02:59.000Z"}"#;
      67            2 : 
      68            2 :         assert_eq!(s, expected);
      69            2 :     }
      70              : }