From fda073a7a56467a7051f311b0923db1e5f3f0afa Mon Sep 17 00:00:00 2001 From: Josh Carp Date: Fri, 27 Feb 2026 17:28:22 -0500 Subject: [PATCH] Document distribution statistics. Distributions have two kinds of statistics: histogram bucket counts, which can be converted from cumulative values to deltas by subtraction; and streaming estimates (min, max, quantiles, etc.), which can't. Because streaming estimates can't be subtracted, they always reflect values since the start of the series's epoch, and can't be used to examine a specific time range (e.g., the last hour). Users should probably use histogram statistics and not streaming statistics for monitoring purposes. This patch updates the inline docs to clarify these differences and steer users toward histograms in most use cases. --- nexus/external-api/src/lib.rs | 1 + .../nexus/nexus-2026022500.0.0-3651d5.json.gitstub | 1 + ...3651d5.json => nexus-2026030200.0.0-00ae45.json} | 6 +++--- openapi/nexus/nexus-latest.json | 2 +- oximeter/oxql-types/src/point.rs | 13 +++++++++++-- 5 files changed, 17 insertions(+), 6 deletions(-) create mode 100644 openapi/nexus/nexus-2026022500.0.0-3651d5.json.gitstub rename openapi/nexus/{nexus-2026022500.0.0-3651d5.json => nexus-2026030200.0.0-00ae45.json} (99%) diff --git a/nexus/external-api/src/lib.rs b/nexus/external-api/src/lib.rs index 61d21eaad5f..b4ec91eec45 100644 --- a/nexus/external-api/src/lib.rs +++ b/nexus/external-api/src/lib.rs @@ -78,6 +78,7 @@ api_versions!([ // | date-based version should be at the top of the list. // v // (next_yyyy_mm_dd_nn, IDENT), + (2026_03_02_00, BUMP_DISTRIBUTION_DOCS), (2026_02_25_00, SET_TARGET_RELEASE_UPDATE_RECOVERY), (2026_02_19_00, REMOVE_SLED_ADD), (2026_02_13_01, BGP_UNNUMBERED_PEERS), diff --git a/openapi/nexus/nexus-2026022500.0.0-3651d5.json.gitstub b/openapi/nexus/nexus-2026022500.0.0-3651d5.json.gitstub new file mode 100644 index 00000000000..23e940ee412 --- /dev/null +++ b/openapi/nexus/nexus-2026022500.0.0-3651d5.json.gitstub @@ -0,0 +1 @@ +0f9cfadc7fdd9c4def675e60a6e2bf65f0d4b52a:openapi/nexus/nexus-2026022500.0.0-3651d5.json diff --git a/openapi/nexus/nexus-2026022500.0.0-3651d5.json b/openapi/nexus/nexus-2026030200.0.0-00ae45.json similarity index 99% rename from openapi/nexus/nexus-2026022500.0.0-3651d5.json rename to openapi/nexus/nexus-2026030200.0.0-00ae45.json index 51c244db04f..4e5607eeb67 100644 --- a/openapi/nexus/nexus-2026022500.0.0-3651d5.json +++ b/openapi/nexus/nexus-2026030200.0.0-00ae45.json @@ -7,7 +7,7 @@ "url": "https://oxide.computer", "email": "api@oxide.computer" }, - "version": "2026022500.0.0" + "version": "2026030200.0.0" }, "paths": { "/device/auth": { @@ -20089,7 +20089,7 @@ ] }, "Distributiondouble": { - "description": "A distribution is a sequence of bins and counts in those bins, and some statistical information tracked to compute the mean, standard deviation, and quantile estimates.\n\nMin, max, and the p-* quantiles are treated as optional due to the possibility of distribution operations, like subtraction.", + "description": "A distribution is a sequence of bins and counts in those bins, and some statistical information tracked to compute the mean, standard deviation, and quantile estimates.\n\nMin, max, and the p-* quantiles are treated as optional because they cannot be subtracted over time to convert from cumulative to delta values.\n\nNote: bin counts can be subtracted over time to calculate rates, which can in turn be used to estimate arbitrary quantiles over arbitrary time ranges. However, other statistical fields represent streaming calculations: their values at a given point represent the cumulative streaming estimate dating to the start time of the relevant series. Use bin counts rather than streaming statistics for use cases that require estimates over specific time ranges.", "type": "object", "properties": { "bins": { @@ -20149,7 +20149,7 @@ ] }, "Distributionint64": { - "description": "A distribution is a sequence of bins and counts in those bins, and some statistical information tracked to compute the mean, standard deviation, and quantile estimates.\n\nMin, max, and the p-* quantiles are treated as optional due to the possibility of distribution operations, like subtraction.", + "description": "A distribution is a sequence of bins and counts in those bins, and some statistical information tracked to compute the mean, standard deviation, and quantile estimates.\n\nMin, max, and the p-* quantiles are treated as optional because they cannot be subtracted over time to convert from cumulative to delta values.\n\nNote: bin counts can be subtracted over time to calculate rates, which can in turn be used to estimate arbitrary quantiles over arbitrary time ranges. However, other statistical fields represent streaming calculations: their values at a given point represent the cumulative streaming estimate dating to the start time of the relevant series. Use bin counts rather than streaming statistics for use cases that require estimates over specific time ranges.", "type": "object", "properties": { "bins": { diff --git a/openapi/nexus/nexus-latest.json b/openapi/nexus/nexus-latest.json index d5c54bb4d8f..f5b800e85c8 120000 --- a/openapi/nexus/nexus-latest.json +++ b/openapi/nexus/nexus-latest.json @@ -1 +1 @@ -nexus-2026022500.0.0-3651d5.json \ No newline at end of file +nexus-2026030200.0.0-00ae45.json \ No newline at end of file diff --git a/oximeter/oxql-types/src/point.rs b/oximeter/oxql-types/src/point.rs index 5cf88e5ff75..82a115aabc0 100644 --- a/oximeter/oxql-types/src/point.rs +++ b/oximeter/oxql-types/src/point.rs @@ -1659,8 +1659,17 @@ impl DistributionSupport for f64 {} /// statistical information tracked to compute the mean, standard deviation, and /// quantile estimates. /// -/// Min, max, and the p-* quantiles are treated as optional due to the -/// possibility of distribution operations, like subtraction. +/// Min, max, and the p-* quantiles are treated as optional because they +/// cannot be subtracted over time to convert from cumulative to delta +/// values. +/// +/// Note: bin counts can be subtracted over time to calculate rates, which +/// can in turn be used to estimate arbitrary quantiles over arbitrary time +/// ranges. However, other statistical fields represent streaming +/// calculations: their values at a given point represent the cumulative +/// streaming estimate dating to the start time of the relevant +/// series. Use bin counts rather than streaming statistics for use +/// cases that require estimates over specific time ranges. #[derive(Clone, Debug, Deserialize, JsonSchema, PartialEq, Serialize)] #[schemars(rename = "Distribution{T}")] pub struct Distribution {