nits

Author: cijothomas

docs/metrics.md

@@ -27,7 +27,8 @@ Status: **Work-In-Progress**
   * [Memory Preallocation](#memory-preallocation)
 * [Metrics Correlation](#metrics-correlation)
 * [Modelling Metric Attributes](#modelling-metric-attributes)
-* [Common Issues Leading to Missing Metrics](#common-issues-that-lead-to-missing-metrics)
+* [Common Issues Leading to Missing
+  Metrics](#common-issues-that-lead-to-missing-metrics)
 
 </details>
 
@@ -61,8 +62,8 @@ instances with the same name. `Meter` is fairly expensive and meant to be reused
 throughout the application. For most applications, a `Meter` should be obtained
 from `global` and saved for re-use.
 
-> [!IMPORTANT]
-> Create your `Meter` instance once at initialization time and store it for reuse throughout your application's lifecycle.
+> [!IMPORTANT] Create your `Meter` instance once at initialization time and
+> store it for reuse throughout your application's lifecycle.
 
 The fully qualified module name might be a good option for the Meter name.
 Optionally, one may create a meter with version, schema_url, and additional
@@ -95,13 +96,12 @@ instruments to their corresponding Rust SDK types.
 
 :heavy_check_mark: You should understand and pick the right instrument type.
 
-> [!NOTE]
-> Picking the right instrument type for your use case is crucial to ensure the
-correct semantics and performance. Check the [Instrument
+> [!NOTE] Picking the right instrument type for your use case is crucial to
+> ensure the correct semantics and performance. Check the [Instrument
 Selection](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/supplementary-guidelines.md#instrument-selection)
 section from the supplementary guidelines for more information.
 
-| OpenTelemetry Specification | OTel Rust Instrument Type |
+| OpenTelemetry Specification | OpenTelemetry Rust Instrument Type |
 | --------------------------- | -------------------- |
 | [Asynchronous Counter](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#asynchronous-counter) | [`ObservableCounter`](https://docs.rs/opentelemetry/latest/opentelemetry/metrics/struct.ObservableCounter.html) |
 | [Asynchronous Gauge](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#asynchronous-gauge) | [`ObservableGauge`](https://docs.rs/opentelemetry/latest/opentelemetry/metrics/struct.ObservableGauge.html) |
@@ -128,8 +128,7 @@ path. Instead, the cloned instance should be stored and reused.
 :stop_sign: You should avoid changing the order of attributes while reporting
 measurements.
 
-> [!WARNING]
-> The last line of code has bad performance since the attributes are
+> [!WARNING] The last line of code has bad performance since the attributes are
 > not following the same order as before:
 
 ```rust
@@ -141,7 +140,9 @@ counter.add(8, &[KeyValue::new("name", "lemon"), KeyValue::new("color", "yellow"
 ```
 
 :heavy_check_mark: If feasible, provide the attributes sorted by `Key`s in
-ascending order to minimize memory usage within the Metrics SDK. Using consistent attribute ordering allows the SDK to efficiently reuse internal data structures.
+ascending order to minimize memory usage within the Metrics SDK. Using
+consistent attribute ordering allows the SDK to efficiently reuse internal data
+structures.
 
 ```rust
 // Good practice: Consistent attribute ordering
@@ -236,8 +237,7 @@ fn setup_metrics(meter: &opentelemetry::metrics::Meter) {
 }
 ```
 
-> [!NOTE]
-> The callbacks in the Observable instruments are invoked by the SDK
+> [!NOTE] The callbacks in the Observable instruments are invoked by the SDK
 > during each export cycle.
 
 ## MeterProvider Management
@@ -290,44 +290,44 @@ follows while implementing the metrics aggregation logic:
 2. [**Cardinality Limits**](#cardinality-limits): the aggregation logic respects
    [cardinality
    limits](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#cardinality-limits),
-   so the SDK does not use an indefinite amount of memory in the event of a cardinality
-   explosion.
+   so the SDK does not use an indefinite amount of memory in the event of a
+   cardinality explosion.
 3. [**Memory Preallocation**](#memory-preallocation): SDK tries to pre-allocate
    the memory it needs at each instrument creation time.
 
 ### Example
 
-Let us take the following example of OTel Rust metrics being used to track the
-number of fruits sold:
+Let us take the following example of OpenTelemetry Rust metrics being used to
+track the number of fruits sold:
 
 * During the time range (T0, T1]:
-  * value = 1, name = `apple`, color = `red`
-  * value = 2, name = `lemon`, color = `yellow`
+  * value = 1, color = `red`, name = `apple`
+  * value = 2, color = `yellow`, name = `lemon`
 * During the time range (T1, T2]:
   * no fruit has been sold
 * During the time range (T2, T3]:
-  * value = 5, name = `apple`, color = `red`
-  * value = 2, name = `apple`, color = `green`
-  * value = 4, name = `lemon`, color = `yellow`
-  * value = 2, name = `lemon`, color = `yellow`
-  * value = 1, name = `lemon`, color = `yellow`
-  * value = 3, name = `lemon`, color = `yellow`
+  * value = 5, color = `red`, name = `apple`
+  * value = 2, color = `green`, name = `apple`
+  * value = 4, color = `yellow`, name = `lemon`
+  * value = 2, color = `yellow`, name = `lemon`
+  * value = 1, color = `yellow`, name = `lemon`
+  * value = 3, color = `yellow`, name = `lemon`
 
 ### Example - Cumulative Aggregation Temporality
 
 If we aggregate and export the metrics using [Cumulative Aggregation
 Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#temporality):
 
 * (T0, T1]
-  * attributes: {name = `apple`, color = `red`}, count: `1`
-  * attributes: {name = `lemon`, color = `yellow`}, count: `2`
+  * attributes: {color = `red`, name = `apple`}, count: `1`
+  * attributes: {color = `yellow`, name = `lemon`}, count: `2`
 * (T0, T2]
-  * attributes: {name = `apple`, color = `red`}, count: `1`
-  * attributes: {name = `lemon`, color = `yellow`}, count: `2`
+  * attributes: {color = `red`, name = `apple`}, count: `1`
+  * attributes: {color = `yellow`, name = `lemon`}, count: `2`
 * (T0, T3]
-  * attributes: {name = `apple`, color = `red`}, count: `6`
-  * attributes: {name = `apple`, color = `green`}, count: `2`
-  * attributes: {name = `lemon`, color = `yellow`}, count: `12`
+  * attributes: {color = `red`, name = `apple`}, count: `6`
+  * attributes: {color = `green`, name = `apple`}, count: `2`
+  * attributes: {color = `yellow`, name = `lemon`}, count: `12`
 
 Note that the start time is not advanced, and the exported values are the
 cumulative total of what happened since the beginning.
@@ -338,14 +338,14 @@ If we aggregate and export the metrics using [Delta Aggregation
 Temporality](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#temporality):
 
 * (T0, T1]
-  * attributes: {name = `apple`, color = `red`}, count: `1`
-  * attributes: {name = `lemon`, color = `yellow`}, count: `2`
+  * attributes: {color = `red`, name = `apple`}, count: `1`
+  * attributes: {color = `yellow`, name = `lemon`}, count: `2`
 * (T1, T2]
   * nothing since we do not have any measurement received
 * (T2, T3]
-  * attributes: {name = `apple`, color = `red`}, count: `5`
-  * attributes: {name = `apple`, color = `green`}, count: `2`
-  * attributes: {name = `lemon`, color = `yellow`}, count: `10`
+  * attributes: {color = `red`, name = `apple`}, count: `5`
+  * attributes: {color = `green`, name = `apple`}, count: `2`
+  * attributes: {color = `yellow`, name = `lemon`}, count: `10`
 
 Note that the start time is advanced after each export, and only the delta since
 last export is exported, allowing the SDK to "forget" previous state.
@@ -358,7 +358,8 @@ Rust aggregates data locally and only exports the aggregated metrics.
 Using the [fruit example](#example), there are six measurements reported during
 the time range `(T2, T3]`. Instead of exporting each individual measurement
 event, the SDK aggregates them and exports only the summarized results. This
-summarization process, illustrated in the following diagram, is known as pre-aggregation:
+summarization process, illustrated in the following diagram, is known as
+pre-aggregation:
 
 ```mermaid
 graph LR
@@ -395,26 +396,26 @@ Pre-aggregation offers several advantages:
    computational load on downstream systems, enabling them to focus on analysis
    and storage.
 
-> [!NOTE]
-> There is no ability to opt out of pre-aggregation in OpenTelemetry.
+> [!NOTE] There is no ability to opt out of pre-aggregation in OpenTelemetry.
 
 ### Cardinality Limits
 
 The number of distinct combinations of attributes for a given metric is referred
 to as the cardinality of that metric. Taking the [fruit example](#example), if
 we know that we can only have apple/lemon as the name, red/yellow/green as the
-color, then we can say the cardinality is 6 (i.e., 2 names × 3 colors = 6 combinations). No matter how many
-fruits we sell, we can always use the following table to summarize the total
-number of fruits based on the name and color.
-
-| Name  | Color  | Count |
-| ----- | ------ | ----- |
-| apple | red    | 6     |
-| apple | yellow | 0     |
-| apple | green  | 2     |
-| lemon | red    | 0     |
-| lemon | yellow | 12    |
-| lemon | green  | 0     |
+color, then we can say the cardinality is 6 (i.e., 2 names × 3 colors = 6
+combinations). No matter how many fruits we sell, we can always use the
+following table to summarize the total number of fruits based on the name and
+color.
+
+| Color  | Name  | Count |
+| ------ | ----- | ----- |
+| red    | apple | 6     |
+| yellow | apple | 0     |
+| green  | apple | 2     |
+| red    | lemon | 0     |
+| yellow | lemon | 12    |
+| green  | lemon | 0     |
 
 In other words, we know how much memory and network are needed to collect and
 transmit these metrics, regardless of the traffic pattern or volume.
@@ -429,7 +430,8 @@ example, it can cause:
 * Surprisingly high costs in the observability system
 * Excessive memory consumption in your application
 * Poor query performance in your metrics backend
-* Potential denial-of-service vulnerability that could be exploited by bad actors
+* Potential denial-of-service vulnerability that could be exploited by bad
+  actors
 
 [Cardinality
 limit](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#cardinality-limits)
@@ -460,8 +462,8 @@ see much higher cardinality due to:
    (This is only applicable to Delta temporality)
 
 Therefore, the actual cardinality in your metrics backend can be orders of
-magnitude higher than what any single OTel SDK process handles in an export
-cycle.
+magnitude higher than what any single OpenTelemetry SDK process handles in an
+export cycle.
 
 #### Cardinality Limits - Implications
 
@@ -533,13 +535,14 @@ During a busy sales period at time (T3, T4], we record:
 
 The exported metrics would be:
 
-* attributes: {name = `apple`, color = `red`, store_location = `Downtown`},
+* attributes: {color = `red`, name = `apple`, store_location = `Downtown`},
     count: `10`
-* attributes: {name = `lemon`, color = `yellow`, store_location = `Uptown`},
+* attributes: {color = `yellow`, name = `lemon`, store_location = `Uptown`},
     count: `5`
-* attributes: {name = `apple`, color = `green`, store_location = `Downtown`},
+* attributes: {color = `green`, name = `apple`, store_location = `Downtown`},
     count: `8`
-* attributes: {`otel.metric.overflow` = `true`}, count: `3` ← Notice this special overflow attribute
+* attributes: {`otel.metric.overflow` = `true`}, count: `3` ← Notice this
+  special overflow attribute
 
   If we later query "How many red apples were sold?" the answer would be 10, not
   13, because the Midtown sales were folded into the overflow bucket. Similarly,
@@ -577,8 +580,8 @@ A better alternative is to use a concept in OpenTelemetry called
 Exemplars provide a mechanism to correlate metrics with traces by sampling
 specific measurements and attaching trace context to them.
 
-> [!NOTE]
-> Currently, exemplars are not yet implemented in the OpenTelemetry Rust SDK.
+> [!NOTE] Currently, exemplars are not yet implemented in the OpenTelemetry Rust
+> SDK.
 
 ## Modelling Metric Attributes
 
@@ -604,8 +607,9 @@ attributes can come from different sources:
 Follow these guidelines when deciding where to attach metric attributes:
 
 * **For static attributes** (constant throughout the process lifetime):
-  * **Resource-level attributes**: If the dimension applies to all metrics (e.g., hostname, datacenter),
-    model it as a Resource attribute, or better yet, let the collector add these automatically.
+  * **Resource-level attributes**: If the dimension applies to all metrics
+    (e.g., hostname, datacenter), model it as a Resource attribute, or better
+    yet, let the collector add these automatically.
 
     ```rust
     // Example: Setting resource-level attributes
@@ -615,8 +619,9 @@ Follow these guidelines when deciding where to attach metric attributes:
     ]);
     ```
 
-  * **Meter-level attributes**: If the dimension applies only to a subset of metrics (e.g., library version),
-    model it as meter-level attributes via `meter_with_scope`.
+  * **Meter-level attributes**: If the dimension applies only to a subset of
+    metrics (e.g., library version), model it as meter-level attributes via
+    `meter_with_scope`.
 
     ```rust
     // Example: Setting meter-level attributes
@@ -629,7 +634,8 @@ Follow these guidelines when deciding where to attach metric attributes:
 
 * **For dynamic attributes** (values that change during execution):
   * Report these via the Metrics API with each measurement.
-  * Be mindful that [cardinality limits](#cardinality-limits) apply to these attributes.
+  * Be mindful that [cardinality limits](#cardinality-limits) apply to these
+    attributes.
 
     ```rust
     // Example: Using dynamic attributes with each measurement
@@ -643,10 +649,14 @@ Follow these guidelines when deciding where to attach metric attributes:
 
 Common pitfalls that can result in missing metrics include:
 
-1. **Invalid instrument names** - OpenTelemetry will not collect metrics from instruments using invalid names. See the [specification for valid syntax](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-name-syntax).
+1. **Invalid instrument names** - OpenTelemetry will not collect metrics from
+   instruments using invalid names. See the [specification for valid
+   syntax](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-name-syntax).
 
-2. **Not calling `shutdown` on the MeterProvider** - Ensure you properly call `shutdown` at application termination to flush any pending metrics.
+2. **Not calling `shutdown` on the MeterProvider** - Ensure you properly call
+   `shutdown` at application termination to flush any pending metrics.
 
-3. **Cardinality explosion** - When too many unique attribute combinations are used, some metrics may be placed in the overflow bucket.
+3. **Cardinality explosion** - When too many unique attribute combinations are
+   used, some metrics may be placed in the overflow bucket.
 
 // TODO: Add more specific examples