Skip to content

Commit 2640681

Browse files
scottaddiescottaddie
authored
Create migration guide for MetricsQueryClient (#54040)
1 parent fe65923 commit 2640681

File tree

2 files changed

+238
-0
lines changed

2 files changed

+238
-0
lines changed

‎sdk/monitor/Azure.ResourceManager.Monitor/src/MigrationGuide.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Guide for migrating from `Azure.Monitor.Query` to `Azure.ResourceManager.Monitor`
2+
3+
This guide assists in migrating metrics query operations in `Azure.Monitor.Query` to the `Azure.ResourceManager.Monitor` library.
4+
5+
## Table of contents
6+
7+
- [Migration benefits](#migration-benefits)
8+
- [Important changes](#important-changes)
9+
- [Package names](#package-names)
10+
- [Namespaces](#namespaces)
11+
- [Client differences](#client-differences)
12+
- [API changes](#api-changes)
13+
- [Query metrics for a single resource](#query-metrics-for-a-single-resource)
14+
- [Get metric definitions for a single resource](#get-metric-definitions-for-a-single-resource)
15+
- [Get metric namespaces for a single resource](#get-metric-namespaces-for-a-single-resource)
16+
17+
## Migration benefits
18+
19+
The Azure Monitor Query library for .NET has been modularized to provide more focused functionality. The operations for querying metrics via `MetricsQueryClient` have moved from the combined `Azure.Monitor.Query` package to a dedicated `Azure.ResourceManager.Monitor` package. This separation offers several advantages:
20+
21+
- Smaller dependency footprint for applications that only need to query metrics for an Azure resource
22+
- More focused API design specific to metrics query operations
23+
- Independent versioning allowing metrics functionality to evolve separately
24+
- Clearer separation of concerns between logs and metrics query operations
25+
26+
## Important changes
27+
28+
### Package names
29+
30+
- Previous package for querying metrics on an Azure resource: `Azure.Monitor.Query`
31+
- New package: `Azure.ResourceManager.Monitor`
32+
33+
### Namespaces
34+
35+
The root namespace has changed to `Azure.ResourceManager.Monitor` in the new package.
36+
37+
### Client differences
38+
39+
In the `Azure.Monitor.Query` package, `MetricsQueryClient` was used for metrics query options on a single Azure resource. That same functionality can be found in `ArmClient` within the `Azure.ResourceManager.Monitor` package. See the [API changes](#api-changes) section for code samples demonstrating the changes.
40+
41+
### API changes
42+
43+
#### Query metrics for a single resource
44+
45+
**Previous code:**
46+
47+
```csharp
48+
const string resourceId =
49+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
50+
51+
MetricsQueryClient client = new(new DefaultAzureCredential());
52+
MetricsQueryResult result = await client.QueryResourceAsync(
53+
resourceId,
54+
["Availability"]);
55+
56+
foreach (MetricResult metric in result.Metrics)
57+
{
58+
// Process each metric as needed
59+
Console.WriteLine($"Metric Name: {metric.Name}, Unit: {metric.Unit}");
60+
}
61+
```
62+
63+
**New code:**
64+
65+
```C# Snippet:QueryResource
66+
const string resourceId =
67+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
68+
69+
ArmClient client = new(new DefaultAzureCredential());
70+
ArmResourceGetMonitorMetricsOptions options = new()
71+
{
72+
Metricnames = "Availability",
73+
};
74+
AsyncPageable<MonitorMetric> metrics = client.GetMonitorMetricsAsync(
75+
new ResourceIdentifier(resourceId),
76+
options);
77+
78+
await foreach (MonitorMetric metric in metrics)
79+
{
80+
// Process each metric as needed
81+
Console.WriteLine($"Metric Name: {metric.Name?.Value}, Unit: {metric.Unit}");
82+
}
83+
```
84+
85+
#### Get metric definitions for a single resource
86+
87+
**Previous code:**
88+
89+
```csharp
90+
const string resourceId =
91+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
92+
const string metricsNamespace = "Microsoft.Storage/storageAccounts";
93+
94+
MetricsQueryClient client = new(new DefaultAzureCredential());
95+
AsyncPageable<MetricDefinition> definitions =
96+
client.GetMetricDefinitionsAsync(resourceId, metricsNamespace);
97+
98+
await foreach (MetricDefinition definition in definitions)
99+
{
100+
// Process each definition as needed
101+
Console.WriteLine($"Metric Name: {definition.Name}, Unit: {definition.Unit}");
102+
}
103+
```
104+
105+
**New code:**
106+
107+
```C# Snippet:GetMetricDefinitions
108+
const string resourceId =
109+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
110+
const string metricsNamespace = "Microsoft.Storage/storageAccounts";
111+
112+
ArmClient client = new(new DefaultAzureCredential());
113+
AsyncPageable<MonitorMetricDefinition> definitions =
114+
client.GetMonitorMetricDefinitionsAsync(new ResourceIdentifier(resourceId), metricsNamespace);
115+
116+
await foreach (MonitorMetricDefinition definition in definitions)
117+
{
118+
// Process each definition as needed
119+
Console.WriteLine($"Metric Name: {definition.Name?.Value}, Unit: {definition.Unit}");
120+
}
121+
```
122+
123+
#### Get metric namespaces for a single resource
124+
125+
**Previous code:**
126+
127+
```csharp
128+
const string resourceId =
129+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
130+
131+
MetricsQueryClient client = new(new DefaultAzureCredential());
132+
AsyncPageable<MetricNamespace> namespaces =
133+
client.GetMetricNamespacesAsync(resourceId);
134+
135+
await foreach (MetricNamespace ns in namespaces)
136+
{
137+
// Process each namespace as needed
138+
Console.WriteLine($"Namespace Name: {ns.Name}, Type: {ns.FullyQualifiedName}");
139+
}
140+
```
141+
142+
**New code:**
143+
144+
```C# Snippet:GetMetricNamespaces
145+
const string resourceId =
146+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
147+
148+
ArmClient client = new(new DefaultAzureCredential());
149+
AsyncPageable<MonitorMetricNamespace> namespaces =
150+
client.GetMonitorMetricNamespacesAsync(new ResourceIdentifier(resourceId));
151+
152+
await foreach (MonitorMetricNamespace ns in namespaces)
153+
{
154+
// Process each namespace as needed
155+
Console.WriteLine($"Namespace Name: {ns.Name}, Type: {ns.MetricNamespaceNameValue}");
156+
}
157+
```

‎sdk/monitor/Azure.ResourceManager.Monitor/tests/Samples/MigrationGuide.cs‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT License.
3+
4+
using System;
5+
using System.Threading.Tasks;
6+
using Azure.Core;
7+
using Azure.Identity;
8+
using Azure.ResourceManager.Monitor.Models;
9+
using NUnit.Framework;
10+
11+
namespace Azure.ResourceManager.Monitor.Tests.Samples
12+
{
13+
internal class MigrationGuide
14+
{
15+
[Test]
16+
[Ignore("Only verifying that the sample builds")]
17+
public async Task QueryResource()
18+
{
19+
#region Snippet:QueryResource
20+
const string resourceId =
21+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
22+
23+
ArmClient client = new(new DefaultAzureCredential());
24+
ArmResourceGetMonitorMetricsOptions options = new()
25+
{
26+
Metricnames = "Availability",
27+
};
28+
AsyncPageable<MonitorMetric> metrics = client.GetMonitorMetricsAsync(
29+
new ResourceIdentifier(resourceId),
30+
options);
31+
32+
await foreach (MonitorMetric metric in metrics)
33+
{
34+
// Process each metric as needed
35+
Console.WriteLine($"Metric Name: {metric.Name?.Value}, Unit: {metric.Unit}");
36+
}
37+
#endregion
38+
}
39+
40+
[Test]
41+
[Ignore("Only verifying that the sample builds")]
42+
public async Task GetMetricDefinitions()
43+
{
44+
#region Snippet:GetMetricDefinitions
45+
const string resourceId =
46+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
47+
const string metricsNamespace = "Microsoft.Storage/storageAccounts";
48+
49+
ArmClient client = new(new DefaultAzureCredential());
50+
AsyncPageable<MonitorMetricDefinition> definitions =
51+
client.GetMonitorMetricDefinitionsAsync(new ResourceIdentifier(resourceId), metricsNamespace);
52+
53+
await foreach (MonitorMetricDefinition definition in definitions)
54+
{
55+
// Process each definition as needed
56+
Console.WriteLine($"Metric Name: {definition.Name?.Value}, Unit: {definition.Unit}");
57+
}
58+
#endregion
59+
}
60+
61+
[Test]
62+
[Ignore("Only verifying that the sample builds")]
63+
public async Task GetMetricNamespaces()
64+
{
65+
#region Snippet:GetMetricNamespaces
66+
const string resourceId =
67+
"/subscriptions/<subscription_id>/resourceGroups/<resource_group_name>/providers/Microsoft.Storage/storageAccounts/<resource_name>";
68+
69+
ArmClient client = new(new DefaultAzureCredential());
70+
AsyncPageable<MonitorMetricNamespace> namespaces =
71+
client.GetMonitorMetricNamespacesAsync(new ResourceIdentifier(resourceId));
72+
73+
await foreach (MonitorMetricNamespace ns in namespaces)
74+
{
75+
// Process each namespace as needed
76+
Console.WriteLine($"Namespace Name: {ns.Name}, Type: {ns.MetricNamespaceNameValue}");
77+
}
78+
#endregion
79+
}
80+
}
81+
}

0 commit comments

Comments
 (0)