From 8f5420344d93e6a37ad5169e00ea173350d664c6 Mon Sep 17 00:00:00 2001 From: Tim O'Brien Date: Wed, 4 Oct 2023 10:17:31 -0700 Subject: [PATCH] #181 - Usage Unit - Review Feedback - Builds out the language in the recommended unit set (#188) This commit adds more specific language to the recommended unit set and guidance on capitalization. The commit also gets a bit more precise on *exactly* what we mean by "you MUST if possible" for units in the recommended set. --- specification/dimensions/usageunit.md | 34 ++++++++++++++++----------- 1 file changed, 20 insertions(+), 14 deletions(-) diff --git a/specification/dimensions/usageunit.md b/specification/dimensions/usageunit.md index da0b4628f..f30316ab6 100644 --- a/specification/dimensions/usageunit.md +++ b/specification/dimensions/usageunit.md @@ -1,8 +1,10 @@ # Usage Unit -Usage Unit refers to a unit of measurement for consumption or usage of resources or services. Usage Unit may differ from published Pricing Unit when providers use different units,  unit increments, or dimensions for calculating cost.  This unit is commonly used when auditing or reconciling consumption or billing data. +Usage Unit refers to a unit of measurement for the consumption or usage of resources or services. The Usage Unit for a particular line item may differ from the published Pricing Unit when providers use different units, unit increments, or dimensions for calculating cost.  This unit is commonly used when auditing or reconciling consumption or billing data. -The UsageUnit column MUST be present and MUST NOT be null or empty. This column is of type String and MUST be composed of the list of recommended units if it is possible to be expressed in the set of possible units. Composite units made from combinations of recommended units is also allowed. E.g. GB/Month.Instead of "per" or "-" to denote a Composite Unit, slash ("/") SHOULD be used as a common convention.  Count based units like requests, instances, tokens SHOULD be expressed as count.   +The UsageUnit column MUST be present and MUST NOT be null or empty. UsageUnit is of type String, and UsageUnit MUST be composed of the list of recommended units or unit abbreviations if it is possible to be expressed with the units listed in "Recommended Unit Set" below. If the UsageUnit value is a composite value made from combinations of one or more units, each component MUST also align with the set of recommended units if possible. For example, a composite unit of "GB/Month" is allowed. + +Instead of "per" or "-" to denote a Composite Unit, slash ("/") SHOULD be used as a common convention.  Count based units like requests, instances, tokens SHOULD be expressed as "count".  For example, if a usage unit is measured as a rate of requests or instances over a period of time, the unit should be listed as "count/day" to signify the number of requests per day. ## Column ID @@ -27,18 +29,22 @@ A unit of measurement for consumption or usage of resources or services. ## Recommended Unit Set -| TIME_UNIT | DATA_UNIT | COUNT_UNIT | PREFIXES | -|------------------|-----------|--------------|-----------------| -| s: second | bit: bit | count: count | Ki: kibi (2^10) | -| min: minute | B: byte | | Mi: mebi (2^20) | -| h: hour | | | Gi: gibi (2^30) | -| d: day | | | Ti: tebi (2^40) | -| wk: week | | | Pi: pebi (2^50) | -| mo: month | | | K: Kilo (10^3) | -| yr: year | | | M: Mega (10^6) | -| ms: milli-second | | | G: Giga (10^9) | -| us: micro-second | | | T: Tera (10^12) | -| ns: nano-second | | | P: Peta (10^15) | +Units listed in the following table are presented in the following format: "abbreviation: unit (numeric prefix unit)". Unit names are all listed with the appropriate capitalization, and abbreviations are all listed in lowercase. The numeric prefix unit is optional, and if present, the numeric prefix unit MUST be used in conjunction with a unit. For example, "KiB" is allowed, but "Ki" is not allowed. + +If the unit is not listed in the table, it is to be used over a functional equivalent with similar meaning or incompatible capitalization. An example of unit now allowed is a unit such as "calls" or "number" to signify the number of times an event occurred in this case, the unit "count" MUST be used to maintain compatibility with this specification. + +| TIME_UNIT | DATA_UNIT | COUNT_UNIT | NUMERIC PREFIXES | +|------------------|-----------|--------------|-------------------------| +| yr: year | bit: bit | cnt: count | Ki: kibi (2^10) | +| mo: month | B: byte | | Mi: mebi (2^20) | +| wk: week | | | Gi: gibi (2^30) | +| d: day | | | Ti: tebi (2^40) | +| h: hour | | | Pi: pebi (2^50) | +| min: minute | | | K: kilo (10^3) | +| s: second | | | M: mega (10^6) | +| ms: millisecond | | | G: giga (10^9) | +| us: microsecond | | | T: tera (10^12) | +| ns: nanosecond | | | P: peta (10^15) | ## Introduced (version)