Open Telemetry: Adds option to opt-in optional dimensions

Microsoft.Azure.Cosmos/src/CosmosClientTelemetryOptions.cs

@@ -61,5 +61,15 @@ public class CosmosClientTelemetryOptions
         /// <remarks>Metrics data can be published to a monitoring system like Prometheus or Azure Monitor, depending on the configured metrics provider.</remarks>
         /// </summary>
         public bool IsClientMetricsEnabled { get; set; }
+
+        /// <summary>
+        /// Gets or sets the configuration for operation-level metrics.
+        /// </summary>
+        public OperationMetricsOptions OperationMetricsOptions { get; set; }
+
+        /// <summary>
+        /// Gets or sets the configuration for network-level metrics.
+        /// </summary>
+        public NetworkMetricsOptions NetworkMetricsOptions { get; set; }
     }
 }

Microsoft.Azure.Cosmos/src/DocumentClient.cs

@@ -954,8 +954,8 @@ internal virtual void Initialize(Uri serviceEndpoint,
 
             if (this.cosmosClientTelemetryOptions.IsClientMetricsEnabled)
             {
-                CosmosDbOperationMeter.Initialize();
-                CosmosDbNetworkMeter.Initialize();
+                CosmosDbOperationMeter.Initialize(this.cosmosClientTelemetryOptions);
+                CosmosDbNetworkMeter.Initialize(this.cosmosClientTelemetryOptions);
 
                 CosmosDbOperationMeter.AddInstanceCount(this.ServiceEndpoint);
             }

Microsoft.Azure.Cosmos/src/NetworkMetricsOptions.cs

@@ -0,0 +1,55 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+
+namespace Microsoft.Azure.Cosmos
+{
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// Represents the configuration options for collecting metrics related to Cosmos DB network operations.
+    /// </summary>
+    public class NetworkMetricsOptions
+    {
+        /// <summary>
+        /// <para>
+        /// Gets or sets a value indicating whether the routing ID (e.g., PK Range ID for Gateway Mode or Partition/Replica information for Direct Mode, if available) 
+        /// should be included in the network metrics.
+        /// </para>
+        /// By default, Routing Id information is not included as a dimension in the network metrics.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Enabling this option provides greater diagnostic granularity, allowing you to identify issues 
+        /// with specific Partition Key Range IDs, replicas, or partitions. 
+        /// However, including the routing ID as a dimension increases the cardinality of metrics. This can result 
+        /// in significantly higher storage costs and generate a large number of metrics with low sample counts, 
+        /// making analysis more challenging.
+        /// </para>
+        /// <para>
+        /// Carefully evaluate whether the additional granularity is necessary 
+        /// for your use case, as it may lead to increased resource consumption and complexity.
+        /// </para>
+        /// </remarks>
+        public bool? IncludeRoutingId { get; set; }
+
+        /// <summary>
+        /// Gets or sets a collection of custom dimensions to include in the network metrics. Each dimension is defined as a key-value pair.
+        /// </summary>
+        /// <example>
+        /// <code language="c#">
+        /// <![CDATA[
+        /// var telemetryOptions = new NetworkMetricsOptions
+        /// {
+        ///     CustomDimensions = new Dictionary<string, string>
+        ///     {
+        ///         { "Region", "EastUS" },
+        ///     }
+        /// };
+        /// ]]>
+        /// </code>
+        /// </example>
+        public IDictionary<string, string> CustomDimensions { get; set; }
+    }
+
+}

Microsoft.Azure.Cosmos/src/OperationMetricsOptions.cs

@@ -0,0 +1,53 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+
+namespace Microsoft.Azure.Cosmos
+{
+    using System.Collections.Generic;
+
+    /// <summary>
+    /// Represents the configuration options for collecting metrics related to Cosmos DB operations.
+    /// </summary>
+    public class OperationMetricsOptions
+    {
+        /// <summary>
+        /// <para>
+        /// Gets or sets a value indicating whether the region information should be included in the operation metrics.
+        /// </para>
+        /// By default, Region information is not included as a dimension in the operation metrics.
+        /// </summary>
+        /// <remarks>
+        /// <para>
+        /// Enabling this option provides greater diagnostic granularity, allowing you to identify issues 
+        /// with specific Partition Key Range IDs, replicas, or partitions. 
+        /// However, including the routing ID as a dimension increases the cardinality of metrics. This can result 
+        /// in significantly higher storage costs and generate a large number of metrics with low sample counts, 
+        /// making analysis more challenging.
+        /// </para>
+        /// <para>
+        /// Carefully evaluate whether the additional granularity is necessary 
+        /// for your use case, as it may lead to increased resource consumption and complexity.
+        /// </para>
+        /// </remarks>
+        public bool? IncludeRegion { get; set; }
+
+        /// <summary>
+        /// Gets or sets a collection of custom dimensions to include in the operation metrics. Each dimension is defined as a key-value pair.
+        /// </summary>
+        /// <example>
+        /// <code language="c#">
+        /// <![CDATA[
+        /// var telemetryOptions = new OperationMetricsOptions
+        /// {
+        ///     CustomDimensions = new Dictionary<string, string>
+        ///     {
+        ///         { "Region", "EastUS" }
+        ///     }
+        /// };
+        /// ]]>
+        /// </code>
+        /// </example>
+        public IDictionary<string, string> CustomDimensions { get; set; }
+    }
+ }

Microsoft.Azure.Cosmos/src/Query/v3Query/QueryIterator.cs

@@ -54,10 +54,15 @@ private QueryIterator(
             this.hasMoreResults = true;
             this.correlatedActivityId = correlatedActivityId;
 
-            this.querySpec = sqlQuerySpec;
             this.container = container;
-            this.operationName = OpenTelemetryConstants.Operations.QueryItems;
-            this.operationType = Documents.OperationType.Query;
+
+            this.SetupInfoForTelemetry(
+                databaseName: container?.Database?.Id,
+                operationName: OpenTelemetryConstants.Operations.QueryItems,
+                operationType: Documents.OperationType.Query,
+                querySpec: sqlQuerySpec,
+                operationMetricsOptions: requestOptions?.OperationMetricsOptions,
+                networkMetricOptions: requestOptions?.NetworkMetricsOptions);
         }
 
         public static QueryIterator Create(

Microsoft.Azure.Cosmos/src/ReadFeed/ReadFeedIteratorCore.cs

@@ -39,9 +39,17 @@ public ReadFeedIteratorCore(
             CancellationToken cancellationToken)
         {
             this.container = container;
-            this.operationName = OpenTelemetryConstants.Operations.ReadFeedRanges;
 
             this.queryRequestOptions = queryRequestOptions;
+
+            this.SetupInfoForTelemetry(
+                databaseName: container?.Database?.Id,
+                operationName: OpenTelemetryConstants.Operations.ReadFeedRanges,
+                operationType: OperationType.ReadFeed,
+                querySpec: null,
+                operationMetricsOptions: queryRequestOptions?.OperationMetricsOptions,
+                networkMetricOptions: queryRequestOptions?.NetworkMetricsOptions);
+
             readFeedPaginationOptions ??= ReadFeedExecutionOptions.Default;
 
             if (!string.IsNullOrEmpty(continuationToken))

Microsoft.Azure.Cosmos/src/RequestOptions/RequestOptions.cs

@@ -178,6 +178,16 @@ internal static void SetSessionToken(RequestMessage request, string sessionToken
             {
                 request.Headers.Add(HttpConstants.HttpHeaders.SessionToken, sessionToken);
             }
-        }
+        }
+
+        /// <summary>
+        /// Gets or sets the configuration for operation-level metrics.
+        /// </summary>
+        public OperationMetricsOptions OperationMetricsOptions { get; set; } = null;
+
+        /// <summary>
+        /// Gets or sets the configuration for network-level metrics.
+        /// </summary>
+        public NetworkMetricsOptions NetworkMetricsOptions { get; set; } = null;
     }
 }

Microsoft.Azure.Cosmos/src/Resource/ClientContextCore.cs

@@ -541,6 +541,7 @@ private async Task<TResult> RunWithDiagnosticsHelperAsync<TResult>(
                             this.client.Endpoint,
                             containerName,
                             databaseName,
+                            requestOptions,
                             attributes: otelAttributes);
                     }
 
@@ -555,6 +556,7 @@ private async Task<TResult> RunWithDiagnosticsHelperAsync<TResult>(
                             gatewayEndpoint,
                             containerName,
                             databaseName,
+                            requestOptions,
                             cosmosException: cosmosException);
                     }
 
@@ -609,6 +611,7 @@ private static void RecordMetrics(Func<string> getOperationName,
             Uri accountName,
             string containerName,
             string databaseName,
+            RequestOptions requestOptions,
             OpenTelemetryAttributes attributes = null,
             Exception cosmosException = null)
         {
@@ -618,13 +621,15 @@ private static void RecordMetrics(Func<string> getOperationName,
                                                  containerName: containerName,
                                                  databaseName: databaseName,
                                                  attributes: attributes,
+                                                 operationMetricsOptions: requestOptions?.OperationMetricsOptions,
                                                  ex: cosmosException);
 
             CosmosDbNetworkMeter.RecordTelemetry(getOperationName: getOperationName,
                                                  accountName: accountName,
                                                  containerName: containerName,
                                                  databaseName: databaseName,
                                                  attributes: attributes,
+                                                 networkMetricsOptions: requestOptions?.NetworkMetricsOptions,
                                                  ex: cosmosException);
         }
 

Microsoft.Azure.Cosmos/src/Resource/FeedIterators/FeedIterator.cs

@@ -8,6 +8,7 @@ namespace Microsoft.Azure.Cosmos
     using System.Threading;
     using System.Threading.Tasks;
     using Microsoft.Azure.Cosmos.Query.Core;
+    using Microsoft.Azure.Documents;
 
     /// <summary>
     /// Cosmos Result set iterator that keeps track of the continuation token when retrieving results form a query.
@@ -151,5 +152,56 @@ public void Dispose()
         /// collect SQL query Specs for tracing
         /// </summary>
         internal SqlQuerySpec querySpec;
+
+        /// <summary>
+        /// Collect operation metrics options for open telemetry metrics
+        /// </summary>
+        internal OperationMetricsOptions operationMetricsOptions;
+
+        /// <summary>
+        /// Collect network metrics options for open telemetry metrics
+        /// </summary>
+        internal NetworkMetricsOptions networkMetricsOptions;
+
+        /// <summary>
+        /// Setup the information required for telemetry
+        /// </summary>
+        /// <param name="feedIteratorInternal"></param>
+        internal void SetupInfoForTelemetry(FeedIterator feedIteratorInternal)
+        {
+            this.SetupInfoForTelemetry(
+                feedIteratorInternal.databaseName,
+                feedIteratorInternal.operationName,
+                feedIteratorInternal.operationType,
+                feedIteratorInternal.querySpec,
+                feedIteratorInternal.operationMetricsOptions,
+                feedIteratorInternal.networkMetricsOptions);
+        }
+
+        /// <summary>
+        /// Setup the information required for telemetry
+        /// </summary>
+        /// <param name="databaseName"></param>
+        /// <param name="operationName"></param>
+        /// <param name="operationType"></param>
+        /// <param name="querySpec"></param>
+        /// <param name="operationMetricsOptions"></param>
+        /// <param name="networkMetricOptions"></param>
+        internal void SetupInfoForTelemetry(string databaseName, 
+            string operationName, 
+            OperationType? operationType, 
+            SqlQuerySpec querySpec, 
+            OperationMetricsOptions operationMetricsOptions, 
+            NetworkMetricsOptions networkMetricOptions)
+        {
+            this.databaseName = databaseName;
+
+            this.operationName = operationName;
+            this.operationType = operationType;
+
+            this.querySpec = querySpec;
+            this.operationMetricsOptions = operationMetricsOptions;
+            this.networkMetricsOptions = networkMetricOptions;
+        }
     }
 }

Microsoft.Azure.Cosmos/src/Resource/FeedIterators/FeedIteratorCore.cs

@@ -47,11 +47,14 @@ public FeedIteratorCore(
             this.requestOptions = options;
             this.hasMoreResultsInternal = true;
 
-            this.databaseName = databaseId;
             this.container = container;
 
-            this.operationName = OpenTelemetryConstants.Operations.QueryItems;
-            this.operationType = OperationType.Query;
+            this.SetupInfoForTelemetry(databaseName: databaseId,
+                operationName: OpenTelemetryConstants.Operations.QueryItems,
+                operationType: OperationType.Query,
+                querySpec: this.querySpec,
+                operationMetricsOptions: options?.OperationMetricsOptions,
+                networkMetricOptions: options?.NetworkMetricsOptions);
         }
 
         public override bool HasMoreResults => this.hasMoreResultsInternal;
@@ -213,13 +216,20 @@ internal FeedIteratorCore(
             this.responseCreator = responseCreator;
             this.feedIterator = feedIterator;
 
-            this.databaseName = feedIterator.databaseName;
-            this.container = feedIterator.container;
+            this.SetupInfoForTelemetry(feedIterator);
+        }
+
+        private void SetupInfoForTelemetry(FeedIterator feedIteratorInternal)
+        {
+            this.container = feedIteratorInternal.container;
+            this.databaseName = feedIteratorInternal.databaseName;
 
-            this.operationName = feedIterator.operationName;
-            this.operationType = feedIterator.operationType;
+            this.operationName = feedIteratorInternal.operationName;
+            this.operationType = feedIteratorInternal.operationType;
 
-            this.querySpec = feedIterator.querySpec;
+            this.querySpec = feedIteratorInternal.querySpec;
+            this.operationMetricsOptions = feedIteratorInternal.operationMetricsOptions;
+            this.networkMetricsOptions = feedIteratorInternal.networkMetricsOptions;
         }
 
         public override bool HasMoreResults => this.feedIterator.HasMoreResults;

Microsoft.Azure.Cosmos/src/Resource/FeedIterators/FeedIteratorInlineCore.cs

@@ -28,12 +28,9 @@ internal FeedIteratorInlineCore(
             this.feedIteratorInternal = feedIteratorInternal;
             this.clientContext = clientContext;
 
-            this.querySpec = feedIteratorInternal.querySpec;
             this.container = feedIteratorInternal.container;
-            this.databaseName = feedIteratorInternal.databaseName;
 
-            this.operationName = feedIteratorInternal.operationName;
-            this.operationType = feedIteratorInternal.operationType;
+            this.SetupInfoForTelemetry(feedIteratorInternal);
         }
 
         internal FeedIteratorInlineCore(
@@ -44,10 +41,8 @@ internal FeedIteratorInlineCore(
             this.clientContext = clientContext;
 
             this.container = feedIteratorInternal.container;
-            this.databaseName = feedIteratorInternal.databaseName;
 
-            this.operationName = feedIteratorInternal.operationName;
-            this.operationType = feedIteratorInternal.operationType;
+            this.SetupInfoForTelemetry(feedIteratorInternal);
         }
 
         public override bool HasMoreResults => this.feedIteratorInternal.HasMoreResults;
@@ -59,7 +54,11 @@ public override Task<ResponseMessage> ReadNextAsync(CancellationToken cancellati
                         containerName: this.container?.Id,
                         databaseName: this.container?.Database?.Id ?? this.databaseName,
                         operationType: Documents.OperationType.ReadFeed,
-                        requestOptions: null,
+                        requestOptions: new RequestOptions()
+                        {
+                            OperationMetricsOptions = this.operationMetricsOptions,
+                            NetworkMetricsOptions = this.networkMetricsOptions,
+                        },
                         task: (trace) => this.feedIteratorInternal.ReadNextAsync(trace, cancellationToken),
                         openTelemetry: new (this.operationName, (response) =>
                         {