updated verbose

open-telemetry · Nov 4, 2024 · c08b60d · c08b60d
1 parent 5d99f6d
commit c08b60d
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 14 deletions.
diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md
@@ -454,6 +454,12 @@ It captures the number of active instances at any given time. Best practices dic
 
 This metric is [recommended][MetricRecommended].
 
+It captures the end to end Latency of Azure Cosmos DB Backend network call.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
+
 <!-- semconv metric.db.client.cosmosdb.request.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -463,7 +469,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.request.duration` | Histogram | `s` | Total time taken by the network call | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.request.duration` | Histogram | `s` | End to end Latency of Azure Cosmos DB Backend network call | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -551,6 +557,19 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It captures the size of request object sent to Azure Cosmos DB backend.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[0, 65536, 131072, 262144, 524288, 1048576, 1572864, 2097152, 2621440, 3145728, 4194304, 6291456, 8388608, 10485760]`.
+
+Explaining bucket configuration:
+
+1. 0, 64 KB, 128 KB, 256 KB, 512 KB: Low-Range Buckets, These smaller buckets capture typical, lightweight requests, often associated with quick read or write operations.
+2. 1 MB, 1.5 MB: Medium-Range Buckets, These mid-sized buckets help identify requests that are moderately large but still manageable for Cosmos DB.
+3. 2 MB: Higher Usage Levels, The 2 MB bucket is critical because it represents the threshold between "normal" and "large" requests.
+4. 2.5 MB, 3 MB, 4 MB, 6 MB, 8 MB, 10 MB: High-Range Buckets, These larger buckets track heavy requests that could be problematic, such as those involving batch operations or complex data structures.
+
 <!-- semconv metric.db.client.cosmosdb.request.body.size -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -560,7 +579,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.request.body.size` | Histogram | `{bytes}` | Size of request object sent over wire | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.request.body.size` | Histogram | `{bytes}` | Size of request object sent to Azure Cosmos DB backend | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -648,6 +667,19 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It is the size of response received from Azure Cosmos DB backend.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[0, 65536, 131072, 262144, 524288, 1048576, 1572864, 2097152, 2621440, 3145728, 4194304, 6291456, 8388608, 10485760]`.
+
+Explaining bucket configuration:
+
+1. 0, 64 KB, 128 KB, 256 KB, 512 KB: Low-Range Buckets, These capture small responses, which are common for brief reads or simple queries. For example, a small document read or a single record fetch might fit within these sizes. Tracking smaller response sizes is useful because they typically represent low-cost, low-latency operations, which are the backbone of many database transactions. This level of detail helps verify that these requests stay efficient and small.
+2. 1 MB, 1.5 MB: Medium-Range Buckets, Responses in this range indicate larger queries, perhaps with more data fields or multiple records.
+3. 2 MB: Higher Usage Levels, This bucket marks the threshold for what might be considered a "large" response. Responses at or above 2 MB are usually a sign of heavy queries that could increase database load and network latency.
+4. 2.5 MB, 3 MB, 4 MB, 6 MB, 8 MB, 10 MB: High-Range Buckets, These larger buckets track responses that involve heavy data loads, such as large result sets from complex queries or high-throughput batch reads.
+
 <!-- semconv metric.db.client.cosmosdb.response.body.size -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -657,7 +689,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.response.body.size` | Histogram | `{bytes}` | Size of response received over wire | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.response.body.size` | Histogram | `{bytes}` | Size of response received from Azure Cosmos DB backend | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -745,6 +777,12 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It is the time taken in creating connection, It is only applicable in Direct Mode.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
+
 <!-- semconv metric.db.client.cosmosdb.request.channel_aquisition.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -754,7 +792,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.request.channel_aquisition.duration` | Histogram | `s` | Time taken in creating connection, It is only available for Direct Mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.request.channel_aquisition.duration` | Histogram | `s` | Time taken in creating connection, It is only applicable in Direct Mode. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -842,6 +880,12 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It captures the Backend Server Latency, i.e. time taken by Azure Cosmos DB server to process the request. It is only applicable in Direct Mode.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
+
 <!-- semconv metric.db.server.cosmosdb.request.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -851,7 +895,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.server.cosmosdb.request.duration` | Histogram | `s` | Backend latency | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.server.cosmosdb.request.duration` | Histogram | `s` | Backend Server Latency, i.e. time taken by Azure Cosmos DB server to process the request. It is only applicable in Direct Mode. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -939,6 +983,12 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It captures transit time that refers to the duration taken by a request to travel across the network—from the moment it leaves the client to when the response is received back at the client. It is only applicable in Direct Mode.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
+
 <!-- semconv metric.db.client.cosmosdb.request.transit.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -948,7 +998,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.request.transit.duration` | Histogram | `s` | Time taken over wire, It is only available for Direct Mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.request.transit.duration` | Histogram | `s` | Transit time refers to the duration taken by a request to travel across the network—from the moment it leaves the client to when the response is received back at the client. It is only applicable in Direct Mode. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -1036,6 +1086,12 @@ and SHOULD be provided **at span creation time** (if provided at all):
 
 This metric is [recommended][MetricRecommended].
 
+It captures the "received" time, that is the duration from when the response is received until it is fully processed by the SDK. It is only applicable in Direct Mode.
+
+this metric SHOULD be specified with
+[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.0/specification/metrics/api.md#instrument-advisory-parameters)
+of `[ 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 5, 10 ]`.
+
 <!-- semconv metric.db.client.cosmosdb.request.received.duration -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
@@ -1045,7 +1101,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `db.client.cosmosdb.request.received.duration` | Histogram | `s` | Time taken by received step in network request pipeline, It is only available for Direct Mode | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `db.client.cosmosdb.request.received.duration` | Histogram | `s` | Received time is the duration from when the response is received until it is fully processed by the SDK. It is only applicable in Direct Mode. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|

diff --git a/model/database/cosmosdb-metrics.yaml b/model/database/cosmosdb-metrics.yaml
@@ -30,7 +30,7 @@ groups:
   - id: metric.db.client.cosmosdb.request.duration
     type: metric
     metric_name: db.client.cosmosdb.request.duration
-    brief: "Total time taken by the network call"
+    brief: "End to end Latency of Azure Cosmos DB Backend network call"
     instrument: histogram
     unit: "s"
     stability: experimental
@@ -39,7 +39,7 @@ groups:
   - id: metric.db.client.cosmosdb.request.body.size
     type: metric
     metric_name: db.client.cosmosdb.request.body.size
-    brief: "Size of request object sent over wire"
+    brief: "Size of request object sent to Azure Cosmos DB backend"
     instrument: histogram
     unit: "{bytes}"
     stability: experimental
@@ -48,7 +48,7 @@ groups:
   - id: metric.db.client.cosmosdb.response.body.size
     type: metric
     metric_name: db.client.cosmosdb.response.body.size
-    brief: "Size of response received over wire"
+    brief: "Size of response received from Azure Cosmos DB backend"
     instrument: histogram
     unit: "{bytes}"
     stability: experimental
@@ -57,7 +57,7 @@ groups:
   - id: metric.db.client.cosmosdb.request.channel_aquisition.duration
     type: metric
     metric_name: db.client.cosmosdb.request.channel_aquisition.duration
-    brief: "Time taken in creating connection, It is only available for Direct Mode"
+    brief: "Time taken in creating connection, It is only applicable in Direct Mode."
     instrument: histogram
     unit: "s"
     stability: experimental
@@ -66,7 +66,7 @@ groups:
   - id: metric.db.server.cosmosdb.request.duration
     type: metric
     metric_name: db.server.cosmosdb.request.duration
-    brief: "Backend latency"
+    brief: "Backend Server Latency, i.e. time taken by Azure Cosmos DB server to process the request. It is only applicable in Direct Mode."
     instrument: histogram
     unit: "s"
     stability: experimental
@@ -75,7 +75,7 @@ groups:
   - id: metric.db.client.cosmosdb.request.transit.duration
     type: metric
     metric_name: db.client.cosmosdb.request.transit.duration
-    brief: "Time taken over wire, It is only available for Direct Mode"
+    brief: "Transit time refers to the duration taken by a request to travel across the network—from the moment it leaves the client to when the response is received back at the client. It is only applicable in Direct Mode."
     instrument: histogram
     unit: "s"
     stability: experimental
@@ -84,7 +84,7 @@ groups:
   - id: metric.db.client.cosmosdb.request.received.duration
     type: metric
     metric_name: db.client.cosmosdb.request.received.duration
-    brief: "Time taken by received step in network request pipeline, It is only available for Direct Mode"
+    brief: "Received time is the duration from when the response is received until it is fully processed by the SDK. It is only applicable in Direct Mode."
     instrument: histogram
     unit: "s"
     stability: experimental