From c08b60df6ec338023521ab0110654ea43a6cd660 Mon Sep 17 00:00:00 2001 From: Sourabh Jain Date: Mon, 4 Nov 2024 07:46:51 +0530 Subject: [PATCH] updated verbose --- docs/database/cosmosdb.md | 70 +++++++++++++++++++++++++--- model/database/cosmosdb-metrics.yaml | 14 +++--- 2 files changed, 70 insertions(+), 14 deletions(-) diff --git a/docs/database/cosmosdb.md b/docs/database/cosmosdb.md index 29642836e8..830f547232 100644 --- 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 ]`. + @@ -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. + @@ -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. + @@ -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 ]`. + @@ -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 ]`. + @@ -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 ]`. + @@ -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 ]`. + @@ -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 index 0a1ea37239..549c3e57bb 100644 --- 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