From 11d9b8830d25952f1393ed9939be5ce298cc0974 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnther=20Foidl?= Date: Tue, 28 Apr 2026 11:40:49 +0200 Subject: [PATCH 1/2] Changed non-units to follow the UCUM standard and OTel convention Specifically changed `{hats}` to be `{hat}` according [Instrument units](https://opentelemetry.io/docs/specs/semconv/general/metrics/#instrument-units): > All non-units that use curly braces to annotate a quantity need to match the grammatical number of the quantity it represent. For example if measuring the number of individual requests to a process the unit would be `{request}`, not `{requests}`. The same applies to `{hat}` and the docs should follow best pratices and conventions. --- docs/core/diagnostics/metrics-instrumentation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/core/diagnostics/metrics-instrumentation.md b/docs/core/diagnostics/metrics-instrumentation.md index 709fe36daeab7..4d66d68cb40e9 100644 --- a/docs/core/diagnostics/metrics-instrumentation.md +++ b/docs/core/diagnostics/metrics-instrumentation.md @@ -366,7 +366,7 @@ class Program { static Meter s_meter = new Meter("HatCo.Store"); static Counter s_hatsSold = s_meter.CreateCounter(name: "hatco.store.hats_sold", - unit: "{hats}", + unit: "{hat}", description: "The number of hats sold in our store"); static void Main(string[] args) @@ -390,18 +390,18 @@ Press p to pause, r to resume, q to quit. Name Current Value [HatCo.Store] - hatco.store.hats_sold ({hats}) 40 + hatco.store.hats_sold ({hat}) 40 ``` -dotnet-counters doesn't currently use the description text in the UI, but it does show the unit when it is provided. In this case, you see "{hats}" +dotnet-counters doesn't currently use the description text in the UI, but it does show the unit when it is provided. In this case, you see "{hat}" has replaced the generic term "Count" that is visible in previous descriptions. ### Best practices - .NET APIs allow any string to be used as the unit, but we recommend using [UCUM](https://ucum.org/), an international standard for unit names. The curly -braces around "{hats}" is part of the UCUM standard, indicating that it is a descriptive annotation rather than a unit name with a standardized meaning like seconds or bytes. +braces around "{hat}" is part of the UCUM standard, indicating that it is a descriptive annotation rather than a unit name with a standardized meaning like seconds or bytes. See also [Metrics semantic conventions - Instrument units](https://opentelemetry.io/docs/specs/semconv/general/metrics/#instrument-units). -- The unit specified in the constructor should describe the units appropriate for an individual measurement. This will sometimes differ from the units on the final reported metric. In this example, each measurement is a number of hats, so "{hats}" is the appropriate unit to pass in the constructor. The collection tool could have calculated the rate of change and derived on its own that the appropriate unit for the calculated rate metric is {hats}/sec. +- The unit specified in the constructor should describe the units appropriate for an individual measurement. This will sometimes differ from the units on the final reported metric. In this example, each measurement is a number of hats, so "{hat}" is the appropriate unit to pass in the constructor. The collection tool could have calculated the rate of change and derived on its own that the appropriate unit for the calculated rate metric is {hat}/sec. - When recording measurements of time, prefer units of seconds recorded as a floating point or double value. From a30c05e300cbc81df9b810e81a4947ac3558797c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnther=20Foidl?= Date: Tue, 28 Apr 2026 23:00:34 +0200 Subject: [PATCH 2/2] Better wording Co-authored-by: Genevieve Warren <24882762+gewarren@users.noreply.github.com> --- docs/core/diagnostics/metrics-instrumentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/metrics-instrumentation.md b/docs/core/diagnostics/metrics-instrumentation.md index 4d66d68cb40e9..7ac0af0ba5854 100644 --- a/docs/core/diagnostics/metrics-instrumentation.md +++ b/docs/core/diagnostics/metrics-instrumentation.md @@ -399,7 +399,7 @@ has replaced the generic term "Count" that is visible in previous descriptions. ### Best practices - .NET APIs allow any string to be used as the unit, but we recommend using [UCUM](https://ucum.org/), an international standard for unit names. The curly -braces around "{hat}" is part of the UCUM standard, indicating that it is a descriptive annotation rather than a unit name with a standardized meaning like seconds or bytes. See also [Metrics semantic conventions - Instrument units](https://opentelemetry.io/docs/specs/semconv/general/metrics/#instrument-units). +braces around "{hat}" is part of the UCUM standard, indicating that it is a descriptive annotation rather than a unit name with a standardized meaning like seconds or bytes. For more information, see [Metrics semantic conventions - Instrument units](https://opentelemetry.io/docs/specs/semconv/general/metrics/#instrument-units). - The unit specified in the constructor should describe the units appropriate for an individual measurement. This will sometimes differ from the units on the final reported metric. In this example, each measurement is a number of hats, so "{hat}" is the appropriate unit to pass in the constructor. The collection tool could have calculated the rate of change and derived on its own that the appropriate unit for the calculated rate metric is {hat}/sec.