Skip to content

Commit 306201f

Browse files
jairmyreesrnagarscottaddieCopilot
authored
Migration guide to Monitor Metrics Query (#46240)
* migration guide first draft * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Srikanta <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Srikanta <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Srikanta <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Srikanta <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Srikanta <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Scott Addie <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Scott Addie <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Scott Addie <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Scott Addie <[email protected]> * migration guide second draft * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Copilot <[email protected]> * Update sdk/monitor/azure-monitor-query/metrics-query-migration-guide.md Co-authored-by: Copilot <[email protected]> * migration guide third draft * migration guide ARM samples * file rename * adding api changes to table of contents --------- Co-authored-by: Srikanta <[email protected]> Co-authored-by: Scott Addie <[email protected]> Co-authored-by: Copilot <[email protected]>
1 parent 76d9e3b commit 306201f

File tree

1 file changed

+313
-0
lines changed

1 file changed

+313
-0
lines changed

‎sdk/monitor/azure-monitor-query/migration-guide-query-metrics.md

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
# Guide for migrating to `azure-monitor-query-metrics` from `azure-monitor-query`
2+
3+
This guide assists in migrating from the metrics functionality in `azure-monitor-query` to the dedicated `azure-monitor-query-metrics` library.
4+
5+
## Table of contents
6+
7+
- [Migration benefits](#migration-benefits)
8+
- [Cross-service library improvements](#cross-service-library-improvements)
9+
- [Important changes](#important-changes)
10+
- [Group ID, artifact ID, and package names](#group-id-artifact-id-and-package-names)
11+
- [Client differences](#client-differences)
12+
- [API Changes](#api-changes)
13+
- [Instantiate metrics clients](#instantiate-metrics-clients)
14+
- [Query metrics for multiple resources](#query-metrics-for-multiple-resources)
15+
- [Setting audience for authentication](#setting-audience-for-authentication)
16+
- [Additional samples](#additional-samples)
17+
18+
## Migration benefits
19+
20+
The Azure Monitor Query library for Java has been modularized to provide more focused functionality. The metrics operations for querying multiple resources have been moved from the combined `azure-monitor-query` package to a dedicated `azure-monitor-query-metrics` package. This separation offers several advantages:
21+
22+
- Smaller dependency footprint for applications that only need metrics functionality for multiple resources
23+
- More focused API design specific to metrics operations
24+
- Independent versioning allowing metrics functionality to evolve separately
25+
- Clearer separation of concerns between logs and metrics operations
26+
27+
## Important changes
28+
29+
### Group ID, artifact ID, and package names
30+
31+
Both libraries have the same group ID (`com.azure`), but the artifact ID and package names have changed:
32+
33+
- Previous artifact ID: `azure-monitor-query`
34+
- New artifact ID: `azure-monitor-query-metrics`
35+
36+
- Previous package for metrics clients: `com.azure.monitor.query`
37+
- New package: `com.azure.monitor.query.metrics`
38+
39+
**Maven dependency changes:**
40+
41+
Previous dependency in `pom.xml`:
42+
```xml
43+
<dependency>
44+
<groupId>com.azure</groupId>
45+
<artifactId>azure-monitor-query</artifactId>
46+
<version>1.x.x</version>
47+
</dependency>
48+
```
49+
50+
New dependency in `pom.xml`:
51+
```xml
52+
<dependency>
53+
<groupId>com.azure</groupId>
54+
<artifactId>azure-monitor-query-metrics</artifactId>
55+
<version>1.x.x</version>
56+
</dependency>
57+
```
58+
59+
### Client differences
60+
61+
It's important to note that the `azure-monitor-query` package contained two sets of metrics clients:
62+
63+
1. `MetricsQueryClient`/`MetricsQueryAsyncClient`: For querying individual resource metrics, namespaces, or definitions from Azure Monitor
64+
2. `MetricsClient`/`MetricsAsyncClient`: For querying metrics from multiple resources at once
65+
66+
The new `azure-monitor-query-metrics` library only includes the functionality previously provided by `MetricsClient`/`MetricsAsyncClient` for querying metrics from multiple resources. If you were using the `MetricsQueryClient`/`MetricsQueryAsyncClient` from the original package, you should migrate to using the ARM library `azure-resourcemanager-monitor` package for that functionality.
67+
68+
Here are some samples on how to use the `azure-resourcemanager-monitor` library:
69+
70+
- [Authenticating the `MonitorManager`](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/resourcemanager/azure-resourcemanager-monitor/src/samples/java/com/azure/resourcemanager/monitor/ReadmeSamples.java)
71+
- [Get metrics and activity logs for a resource](https://github.com/Azure-Samples/monitor-java-query-metrics-activitylogs)
72+
- [Configuring activity log alerts to be triggered on potential security breaches or risks.](https://github.com/Azure-Samples/monitor-java-activitylog-alerts-on-security-breach-or-risk)
73+
- [Configuring metric alerts to be triggered on potential performance downgrade.](https://github.com/Azure-Samples/monitor-java-metric-alerts-on-critical-performance)
74+
- [Configuring autoscale settings to scale out based on webapp request count statistic.](https://github.com/Azure-Samples/monitor-java-autoscale-based-on-performance)
75+
76+
_Note: If you only need to query metrics from multiple resources, you should migrate to the `azure-monitor-query-metrics` package._
77+
78+
### API changes
79+
80+
The following API changes were made between `azure-monitor-query` and `azure-monitor-query-metrics`:
81+
82+
| `azure-monitor-query` | `azure-monitor-query-metrics` | Notes |
83+
|------------------------|------------------------------|-------|
84+
| `com.azure.monitor.query.models.QueryTimeInterval` | `com.azure.monitor.query.metrics.models.MetricsQueryTimeInterval` | Used to specify the time range for metrics queries |
85+
86+
Code using the previous `QueryTimeInterval` class will need to be updated to use the new `MetricsQueryTimeInterval` class:
87+
88+
Previous code:
89+
```java
90+
import com.azure.monitor.query.models.QueryTimeInterval;
91+
import java.time.OffsetDateTime;
92+
93+
public class QueryTimeIntervalSample {
94+
public static void main(String[] args) {
95+
// Create a time interval with explicit start and end times
96+
OffsetDateTime endTime = OffsetDateTime.now();
97+
OffsetDateTime startTime = endTime.minusHours(24);
98+
QueryTimeInterval timeInterval = new QueryTimeInterval(startTime, endTime);
99+
100+
System.out.println("Time interval created from " + timeInterval.getStartTime() +
101+
" to " + timeInterval.getEndTime());
102+
}
103+
}
104+
```
105+
106+
New code:
107+
```java
108+
import com.azure.monitor.query.metrics.models.MetricsQueryTimeInterval;
109+
import java.time.OffsetDateTime;
110+
111+
public class MetricsQueryTimeIntervalSample {
112+
public static void main(String[] args) {
113+
// Create a time interval with explicit start and end times
114+
OffsetDateTime endTime = OffsetDateTime.now();
115+
OffsetDateTime startTime = endTime.minusHours(24);
116+
MetricsQueryTimeInterval timeInterval = new MetricsQueryTimeInterval(startTime, endTime);
117+
118+
System.out.println("Time interval created from " + timeInterval.getStartTime() +
119+
" to " + timeInterval.getEndTime());
120+
}
121+
}
122+
```
123+
124+
Note that the Metrics service only supports time intervals with explicit start and end times. Do not use duration-based time intervals when querying metrics.
125+
Duration-based `MetricsQueryTimeInterval` is not supported in the `azure-monitor-query-metrics` library.
126+
127+
### Instantiate metrics clients
128+
129+
In `azure-monitor-query`, metrics functionality was accessed through the `MetricsClient` and `MetricsAsyncClient` classes:
130+
131+
```java
132+
import com.azure.monitor.query.MetricsClient;
133+
import com.azure.monitor.query.MetricsClientBuilder;
134+
import com.azure.monitor.query.MetricsAsyncClient;
135+
import com.azure.identity.DefaultAzureCredentialBuilder;
136+
import com.azure.core.credential.TokenCredential;
137+
138+
public class MetricsClientSample {
139+
public static void main(String[] args) {
140+
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
141+
142+
// Create synchronous client
143+
MetricsClient metricsClient = new MetricsClientBuilder()
144+
.credential(tokenCredential)
145+
.buildClient();
146+
147+
// Create asynchronous client
148+
MetricsAsyncClient metricsAsyncClient = new MetricsClientBuilder()
149+
.credential(tokenCredential)
150+
.buildAsyncClient();
151+
152+
System.out.println("Successfully created metrics clients");
153+
}
154+
}
155+
```
156+
157+
In `azure-monitor-query-metrics`, the class names remain the same but the package names used in import statements should be updated to `com.azure.monitor.query.metrics.*`:
158+
159+
```java
160+
import com.azure.monitor.query.metrics.MetricsClient;
161+
import com.azure.monitor.query.metrics.MetricsClientBuilder;
162+
import com.azure.monitor.query.metrics.MetricsAsyncClient;
163+
import com.azure.identity.DefaultAzureCredentialBuilder;
164+
import com.azure.core.credential.TokenCredential;
165+
166+
public class MetricsClientSample {
167+
public static void main(String[] args) {
168+
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
169+
170+
// Create synchronous client
171+
MetricsClient metricsClient = new MetricsClientBuilder()
172+
.credential(tokenCredential)
173+
.buildClient();
174+
175+
// Create asynchronous client
176+
MetricsAsyncClient metricsAsyncClient = new MetricsClientBuilder()
177+
.credential(tokenCredential)
178+
.buildAsyncClient();
179+
180+
System.out.println("Successfully created metrics clients");
181+
}
182+
}
183+
```
184+
185+
### Query metrics for multiple resources
186+
187+
The method signatures for querying metrics for multiple resources remain largely the same, but you'll need to update the import statements:
188+
189+
Previous code:
190+
```java
191+
import com.azure.monitor.query.MetricsClient;
192+
import com.azure.monitor.query.MetricsClientBuilder;
193+
import com.azure.monitor.query.models.MetricsQueryResult;
194+
import com.azure.monitor.query.models.MetricsQueryResourcesOptions;
195+
import com.azure.monitor.query.models.QueryTimeInterval;
196+
import com.azure.identity.DefaultAzureCredentialBuilder;
197+
import com.azure.core.credential.TokenCredential;
198+
import java.util.Arrays;
199+
import java.util.Map;
200+
import java.time.Duration;
201+
import java.time.OffsetDateTime;
202+
203+
public class MultiResourceMetricsQuerySample {
204+
public static void main(String[] args) {
205+
// Replace these with actual resource IDs from your Azure subscription
206+
String resourceId1 = "<resource-id-1>";
207+
String resourceId2 = "<resource-id-2>";
208+
209+
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
210+
211+
MetricsClient metricsClient = new MetricsClientBuilder()
212+
.credential(tokenCredential)
213+
.buildClient();
214+
215+
// Define the time range for the query
216+
OffsetDateTime endTime = OffsetDateTime.now();
217+
OffsetDateTime startTime = endTime.minusHours(24);
218+
219+
// Example operation for multiple resources
220+
Map<String, MetricsQueryResult> results = metricsClient.queryResources(
221+
Arrays.asList(resourceId1, resourceId2),
222+
Arrays.asList("SuccessfulCalls", "FailedCalls"),
223+
new MetricsQueryResourcesOptions()
224+
.setGranularity(Duration.ofHours(1))
225+
.setTimeInterval(new QueryTimeInterval(startTime, endTime)));
226+
227+
// Process the results
228+
results.forEach((resourceId, result) -> {
229+
System.out.println("Results for resource: " + resourceId);
230+
System.out.println("Metrics count: " + result.getMetrics().size());
231+
});
232+
}
233+
}
234+
```
235+
236+
New code:
237+
```java
238+
import com.azure.monitor.query.metrics.MetricsClient;
239+
import com.azure.monitor.query.metrics.MetricsClientBuilder;
240+
import com.azure.monitor.query.metrics.models.MetricsQueryResult;
241+
import com.azure.monitor.query.metrics.models.MetricsQueryResourcesOptions;
242+
import com.azure.monitor.query.metrics.models.MetricsQueryTimeInterval;
243+
import com.azure.identity.DefaultAzureCredentialBuilder;
244+
import com.azure.core.credential.TokenCredential;
245+
import java.util.Arrays;
246+
import java.util.Map;
247+
import java.time.Duration;
248+
import java.time.OffsetDateTime;
249+
250+
public class MultiResourceMetricsQuerySample {
251+
public static void main(String[] args) {
252+
// Replace these with actual resource IDs from your Azure subscription
253+
String resourceId1 = "<resource-id-1>";
254+
String resourceId2 = "<resource-id-2>";
255+
256+
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
257+
258+
MetricsClient metricsClient = new MetricsClientBuilder()
259+
.credential(tokenCredential)
260+
.buildClient();
261+
262+
// Define the time range for the query
263+
OffsetDateTime endTime = OffsetDateTime.now();
264+
OffsetDateTime startTime = endTime.minusHours(24);
265+
266+
// Example operation for multiple resources
267+
Map<String, MetricsQueryResult> results = metricsClient.queryResources(
268+
Arrays.asList(resourceId1, resourceId2),
269+
Arrays.asList("SuccessfulCalls", "FailedCalls"),
270+
new MetricsQueryResourcesOptions()
271+
.setGranularity(Duration.ofHours(1))
272+
.setTimeInterval(new MetricsQueryTimeInterval(startTime, endTime)));
273+
274+
// Process the results
275+
results.forEach((resourceId, result) -> {
276+
System.out.println("Results for resource: " + resourceId);
277+
System.out.println("Metrics count: " + result.getMetrics().size());
278+
});
279+
}
280+
}
281+
```
282+
283+
### Setting audience for authentication
284+
285+
The new `azure-monitor-query-metrics` library supports specifying the audience for authentication. This is useful when working with custom Azure environments:
286+
287+
```java
288+
import com.azure.monitor.query.metrics.MetricsClient;
289+
import com.azure.monitor.query.metrics.MetricsClientBuilder;
290+
import com.azure.monitor.query.metrics.models.MetricsQueryAudience;
291+
import com.azure.identity.DefaultAzureCredentialBuilder;
292+
import com.azure.core.credential.TokenCredential;
293+
294+
public class MetricsAudienceSample {
295+
public static void main(String[] args) {
296+
TokenCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
297+
298+
// Create client with custom audience
299+
MetricsClient metricsClient = new MetricsClientBuilder()
300+
.credential(tokenCredential)
301+
.audience(MetricsQueryAudience.AZURE_CLOUD) // Set the audience for authentication
302+
.buildClient();
303+
304+
System.out.println("Created metrics client with custom audience");
305+
306+
// Now you can use the client to query metrics with the specified audience
307+
}
308+
}
309+
```
310+
311+
## Additional samples
312+
313+
More examples can be found in the [Azure Monitor Query Metrics samples](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query-metrics/src/samples/java/README.md).

0 commit comments

Comments
 (0)