From 2fe81f803f9557b9a8c910ca772c18e2364f4c31 Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 8 Dec 2025 10:55:19 +0100 Subject: [PATCH 1/2] updating docs again --- docs/core/diagnostics/metrics-generator.md | 25 ------------------- .../diagnostics/metrics-strongly-typed.md | 20 --------------- 2 files changed, 45 deletions(-) diff --git a/docs/core/diagnostics/metrics-generator.md b/docs/core/diagnostics/metrics-generator.md index e68ec8599ee25..ff80bea2499f1 100644 --- a/docs/core/diagnostics/metrics-generator.md +++ b/docs/core/diagnostics/metrics-generator.md @@ -49,31 +49,6 @@ The following code demonstrates how to use the generator with primitive types: :::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="metrics" ::: -## Specifying units - -You can optionally specify a unit of measurement for your metrics using the `Unit` parameter. This helps provide context about what the metric measures (for example, "seconds", "bytes", and "requests"). The unit is passed to the underlying when creating the instrument. - -The following code demonstrates how to use the generator with primitive types with units specified: - -```csharp -internal static partial class Metric -{ - [Histogram("requestName", "duration", Name = "MyCustomMetricName", Unit = "ms")] - public static partial Latency CreateLatency(Meter meter); - - [Counter( - MetricConstants.EnvironmentName, - MetricConstants.Region, - MetricConstants.RequestName, - MetricConstants.RequestStatus, - Unit = "requests")] - public static partial TotalCount CreateTotalCount(Meter meter); - - [Counter(Unit = "failures")] - public static partial TotalFailures CreateTotalFailures(this Meter meter); -} -``` - The previous declaration automatically returns the following: - `Latency` class with a `Record` method diff --git a/docs/core/diagnostics/metrics-strongly-typed.md b/docs/core/diagnostics/metrics-strongly-typed.md index 6f521c9014f5d..d2871191458c1 100644 --- a/docs/core/diagnostics/metrics-strongly-typed.md +++ b/docs/core/diagnostics/metrics-strongly-typed.md @@ -78,26 +78,6 @@ The following code shows how to create and use these metrics in a class: In the preceding `MyClass.DoWork` method, a `MetricTags` object is populated with values for each tag. This single `tags` object is then passed to all three instruments when recording data. The `Latency` metric (a histogram) records the elapsed time, and both counters (`TotalCount` and `TotalFailures`) record occurrence counts. Because all metrics share the same tag object type, the tags (`Dim1DimensionName`, `Operation`, `Dim2`, `Dim3`, `DimensionNameOfParentOperation`) are present on every measurement. -## Specifying units - -You can optionally specify a unit of measurement for your metrics using the `Unit` parameter. This helps provide context about what the metric measures (for example, "seconds", "bytes", and "requests"). The unit is passed to the underlying when creating the instrument. - -The following code demonstrates how to use the generator with primitive types with units specified: - -```csharp -public static partial class Metric -{ - [Histogram(typeof(MetricTags), Unit = "ms")] - public static partial Latency CreateLatency(Meter meter); - - [Counter(typeof(MetricTags), Unit = "requests")] - public static partial TotalCount CreateTotalCount(Meter meter); - - [Counter(typeof(MetricTags), Unit = "failures")] - public static partial TotalFailures CreateTotalFailures(Meter meter); -} -``` - ## Performance considerations Using strongly-typed tags via source generation adds no overhead compared to using metrics directly. If you need to further minimize allocations for very high-frequency metrics, consider defining your tag object as a `struct` (value type) instead of a `class`. Using a `struct` for the tag object can avoid heap allocations when recording metrics, since the tags would be passed by value. From 37f85048bb9c285bdfd0ef905e284ef5b0389fbc Mon Sep 17 00:00:00 2001 From: Mariam Aziz Date: Mon, 8 Dec 2025 21:15:29 +0100 Subject: [PATCH 2/2] adding note --- docs/core/diagnostics/metrics-generator.md | 25 +++++++++++++++++++ .../diagnostics/metrics-strongly-typed.md | 20 +++++++++++++++ 2 files changed, 45 insertions(+) diff --git a/docs/core/diagnostics/metrics-generator.md b/docs/core/diagnostics/metrics-generator.md index ff80bea2499f1..e2323218a9fb5 100644 --- a/docs/core/diagnostics/metrics-generator.md +++ b/docs/core/diagnostics/metrics-generator.md @@ -49,6 +49,31 @@ The following code demonstrates how to use the generator with primitive types: :::code language="csharp" source="snippets/MetricsGen/Metrics.cs" id="metrics" ::: +## Specifying units + +Starting with .NET 10.2, you can optionally specify a unit of measurement for your metrics using the `Unit` parameter. This helps provide context about what the metric measures (for example, "seconds", "bytes", and "requests"). The unit is passed to the underlying when creating the instrument. + +The following code demonstrates how to use the generator with primitive types with units specified: + +```csharp +internal static partial class Metric +{ + [Histogram("requestName", "duration", Name = "MyCustomMetricName", Unit = "ms")] + public static partial Latency CreateLatency(Meter meter); + + [Counter( + MetricConstants.EnvironmentName, + MetricConstants.Region, + MetricConstants.RequestName, + MetricConstants.RequestStatus, + Unit = "requests")] + public static partial TotalCount CreateTotalCount(Meter meter); + + [Counter(Unit = "failures")] + public static partial TotalFailures CreateTotalFailures(this Meter meter); +} +``` + The previous declaration automatically returns the following: - `Latency` class with a `Record` method diff --git a/docs/core/diagnostics/metrics-strongly-typed.md b/docs/core/diagnostics/metrics-strongly-typed.md index d2871191458c1..15339e5a96d4f 100644 --- a/docs/core/diagnostics/metrics-strongly-typed.md +++ b/docs/core/diagnostics/metrics-strongly-typed.md @@ -78,6 +78,26 @@ The following code shows how to create and use these metrics in a class: In the preceding `MyClass.DoWork` method, a `MetricTags` object is populated with values for each tag. This single `tags` object is then passed to all three instruments when recording data. The `Latency` metric (a histogram) records the elapsed time, and both counters (`TotalCount` and `TotalFailures`) record occurrence counts. Because all metrics share the same tag object type, the tags (`Dim1DimensionName`, `Operation`, `Dim2`, `Dim3`, `DimensionNameOfParentOperation`) are present on every measurement. +## Specifying units + +Starting with .NET 10.2, you can optionally specify a unit of measurement for your metrics using the `Unit` parameter. This helps provide context about what the metric measures (for example, "seconds", "bytes", and "requests"). The unit is passed to the underlying when creating the instrument. + +The following code demonstrates how to use the generator with primitive types with units specified: + +```csharp +public static partial class Metric +{ + [Histogram(typeof(MetricTags), Unit = "ms")] + public static partial Latency CreateLatency(Meter meter); + + [Counter(typeof(MetricTags), Unit = "requests")] + public static partial TotalCount CreateTotalCount(Meter meter); + + [Counter(typeof(MetricTags), Unit = "failures")] + public static partial TotalFailures CreateTotalFailures(Meter meter); +} +``` + ## Performance considerations Using strongly-typed tags via source generation adds no overhead compared to using metrics directly. If you need to further minimize allocations for very high-frequency metrics, consider defining your tag object as a `struct` (value type) instead of a `class`. Using a `struct` for the tag object can avoid heap allocations when recording metrics, since the tags would be passed by value.