Add Monitor Query README section for metric splitting (Azure#36053)

* Add Monitor Query README section for metric splitting

* React to feedback

* Enable query metrics tests

* Move comment

Author: scottaddie

sdk/monitor/Azure.Monitor.Query/README.md

@@ -99,6 +99,7 @@ All client instance methods are thread-safe and independent of each other ([guid
 - [Metrics query](#metrics-query)
   - [Handle metrics query response](#handle-metrics-query-response)
   - [Query metrics with options](#query-metrics-with-options)
+  - [Split a metric by dimension](#split-a-metric-by-dimension)
 - [Register the client with dependency injection](#register-the-client-with-dependency-injection)
 
 ### Logs query
@@ -429,7 +430,7 @@ var client = new MetricsQueryClient(new DefaultAzureCredential());
 
 Response<MetricsQueryResult> results = await client.QueryResourceAsync(
     resourceId,
-    new[] { "SuccessfulCalls", "TotalCalls" }
+    new[] { "Query Success Rate", "Query Count" }
 );
 
 foreach (MetricResult metric in results.Value.Metrics)
@@ -479,11 +480,12 @@ A `MetricsQueryOptions` object may be used to support more granular metrics quer
 ```C# Snippet:QueryMetricsWithAggregations
 string resourceId =
     "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.KeyVault/vaults/TestVault";
+string[] metricNames = new[] { "Availability" };
 var client = new MetricsQueryClient(new DefaultAzureCredential());
 
 Response<MetricsQueryResult> result = await client.QueryResourceAsync(
     resourceId,
-    new[] { "Availability" },
+    metricNames,
     new MetricsQueryOptions
     {
         Aggregations =
@@ -505,6 +507,48 @@ foreach (MetricTimeSeriesElement element in metric.TimeSeries)
 }
 ```
 
+#### Split a metric by dimension
+
+The [MetricsQueryOptions.Filter](https://learn.microsoft.com/dotnet/api/azure.monitor.query.metricsqueryoptions.filter?view=azure-dotnet#azure-monitor-query-metricsqueryoptions-filter) property can be used for [splitting a metric](https://learn.microsoft.com/azure/azure-monitor/essentials/metrics-charts#metric-splitting) by a dimension when its filter value is set to an asterisk. Consider the following example for an App Service resource named *TestWebApp*. The code queries the resource's `Http2xx` metric and splits it by the `Instance` dimension.
+
+```C# Snippet:QueryMetricsWithSplitting
+string resourceId =
+    "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Web/sites/TestWebApp";
+string[] metricNames = new[] { "Http2xx" };
+// Use of asterisk in filter value enables splitting on Instance dimension.
+string filter = "Instance eq '*'";
+var client = new MetricsQueryClient(new DefaultAzureCredential());
+var options = new MetricsQueryOptions
+{
+    Aggregations =
+    {
+        MetricAggregationType.Average,
+    },
+    Filter = filter,
+    TimeRange = TimeSpan.FromDays(2),
+};
+Response<MetricsQueryResult> result = await client.QueryResourceAsync(
+    resourceId,
+    metricNames,
+    options);
+
+foreach (MetricResult metric in result.Value.Metrics)
+{
+    foreach (MetricTimeSeriesElement element in metric.TimeSeries)
+    {
+        foreach (MetricValue value in element.Values)
+        {
+            // Prints a line that looks like the following:
+            // Thursday, May 4, 2023 9:42:00 PM, webwk000002, Http2xx, 1
+            Console.WriteLine(
+                $"{value.TimeStamp:F}, {element.Metadata["Instance"]}, {metric.Name}, {value.Average}");
+        }
+    }
+}
+```
+
+For an inventory of metrics and dimensions available for each Azure resource type, see [Supported metrics with Azure Monitor](https://learn.microsoft.com/azure/azure-monitor/essentials/metrics-supported).
+
 #### Register the client with dependency injection
 
 To register `LogsQueryClient` with the dependency injection (DI) container, invoke the `AddLogsQueryClient` method. To register `MetricsQueryClient` with the dependency injection (DI) container, invoke the `AddMetricsQueryClient` method. For more information, see [Register client](https://learn.microsoft.com/dotnet/azure/sdk/dependency-injection#register-client).

sdk/monitor/Azure.Monitor.Query/src/MetricsQueryClient.cs

@@ -90,7 +90,7 @@ protected MetricsQueryClient()
         ///
         /// Response<MetricsQueryResult> results = await client.QueryResourceAsync(
         ///     resourceId,
-        ///     new[] { "SuccessfulCalls", "TotalCalls" }
+        ///     new[] { "Query Success Rate", "Query Count" }
         /// );
         ///
         /// foreach (MetricResult metric in results.Value.Metrics)
@@ -151,7 +151,7 @@ public virtual Response<MetricsQueryResult> QueryResource(string resourceId, IEn
         ///
         /// Response&lt;MetricsQueryResult&gt; results = await client.QueryResourceAsync(
         ///     resourceId,
-        ///     new[] { &quot;SuccessfulCalls&quot;, &quot;TotalCalls&quot; }
+        ///     new[] { &quot;Query Success Rate&quot;, &quot;Query Count&quot; }
         /// );
         ///
         /// foreach (MetricResult metric in results.Value.Metrics)

sdk/monitor/Azure.Monitor.Query/src/MetricsQueryOptions.cs

@@ -31,7 +31,7 @@ public class MetricsQueryOptions
         /// </para>
         /// <para>
         /// Although this collection cannot be set, it can be modified.
-        /// See <see href="https://docs.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#object-initializers-with-collection-read-only-property-initialization">Object initializers with collection read-only property initialization</see>.
+        /// See <see href="https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/object-and-collection-initializers#object-initializers-with-collection-read-only-property-initialization">Object initializers with collection read-only property initialization</see>.
         /// </para>
         /// </summary>
         public IList<MetricAggregationType> Aggregations { get; } = new List<MetricAggregationType>();
@@ -45,7 +45,7 @@ public class MetricsQueryOptions
         /// <summary>
         /// Gets or sets the filter that is used to refine the set of metric data returned.
         /// <example>
-        /// MetricResult contains metadata A, B and C.<br/>
+        /// <see cref="MetricResult"/> contains metadata A, B, and C.<br/>
         /// <br/>
         ///     - Return all time series of C where A = a1 and B = b1 or b2:<br/>
         ///         <c>A eq 'a1' and B eq 'b1' or B eq 'b2' and C eq '*'</c><br/>

sdk/monitor/Azure.Monitor.Query/tests/MetricsQueryClientSamples.cs

@@ -4,6 +4,7 @@
 using System;
 using System.Threading.Tasks;
 using Azure.Core.TestFramework;
+using Azure.Identity;
 using Azure.Monitor.Query.Models;
 using NUnit.Framework;
 
@@ -12,7 +13,6 @@ namespace Azure.Monitor.Query.Tests
     public class MetricsQueryClientSamples: SamplesBase<MonitorQueryTestEnvironment>
     {
         [Test]
-        [Ignore("https://github.com/Azure/azure-sdk-for-net/issues/21657")]
         public async Task QueryMetrics()
         {
             #region Snippet:QueryMetrics
@@ -28,7 +28,7 @@ public async Task QueryMetrics()
 
             Response<MetricsQueryResult> results = await client.QueryResourceAsync(
                 resourceId,
-                new[] { "SuccessfulCalls", "TotalCalls" }
+                new[] { "Query Success Rate", "Query Count" }
             );
 
             foreach (MetricResult metric in results.Value.Metrics)
@@ -48,21 +48,22 @@ public async Task QueryMetrics()
         }
 
         [Test]
-        [Ignore("https://github.com/Azure/azure-sdk-for-net/issues/21657")]
         public async Task QueryMetricsWithAggregations()
         {
             #region Snippet:QueryMetricsWithAggregations
 #if SNIPPET
             string resourceId =
                 "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.KeyVault/vaults/TestVault";
+            string[] metricNames = new[] { "Availability" };
 #else
             string resourceId = TestEnvironment.MetricsResource;
+            string[] metricNames = new[] { "Heartbeat" };
 #endif
             var client = new MetricsQueryClient(new DefaultAzureCredential());
 
             Response<MetricsQueryResult> result = await client.QueryResourceAsync(
                 resourceId,
-                new[] { "Availability" },
+                metricNames,
                 new MetricsQueryOptions
                 {
                     Aggregations =
@@ -84,5 +85,51 @@ public async Task QueryMetricsWithAggregations()
             }
             #endregion
         }
+
+        [Test]
+        public async Task QueryMetricsWithSplitting()
+        {
+            #region Snippet:QueryMetricsWithSplitting
+#if SNIPPET
+            string resourceId =
+                "/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Web/sites/TestWebApp";
+            string[] metricNames = new[] { "Http2xx" };
+            // Use of asterisk in filter value enables splitting on Instance dimension.
+            string filter = "Instance eq '*'";
+#else
+            string resourceId = TestEnvironment.MetricsResource;
+            string[] metricNames = new[] { "Average_% Available Memory" };
+            string filter = "Computer eq '*'";
+#endif
+            var client = new MetricsQueryClient(new DefaultAzureCredential());
+            var options = new MetricsQueryOptions
+            {
+                Aggregations =
+                {
+                    MetricAggregationType.Average,
+                },
+                Filter = filter,
+                TimeRange = TimeSpan.FromDays(2),
+            };
+            Response<MetricsQueryResult> result = await client.QueryResourceAsync(
+                resourceId,
+                metricNames,
+                options);
+
+            foreach (MetricResult metric in result.Value.Metrics)
+            {
+                foreach (MetricTimeSeriesElement element in metric.TimeSeries)
+                {
+                    foreach (MetricValue value in element.Values)
+                    {
+                        // Prints a line that looks like the following:
+                        // Thursday, May 4, 2023 9:42:00 PM, webwk000002, Http2xx, 1
+                        Console.WriteLine(
+                            $"{value.TimeStamp:F}, {element.Metadata["Instance"]}, {metric.Name}, {value.Average}");
+                    }
+                }
+            }
+            #endregion
+        }
     }
 }