Azure Monitor Query Java

1---
2name: azure-monitor-query-java
3description: |
4  Azure Monitor Query SDK for Java. Execute Kusto queries against Log Analytics workspaces and query metrics from Azure resources.
5  Triggers: "LogsQueryClient java", "MetricsQueryClient java", "kusto query java", "log analytics java", "azure monitor query java".
6  Note: This package is deprecated. Migrate to azure-monitor-query-logs and azure-monitor-query-metrics.
7package: com.azure:azure-monitor-query
8---
9 
10# Azure Monitor Query SDK for Java
11 
12> **DEPRECATION NOTICE**: This package is deprecated in favor of:
13> - `azure-monitor-query-logs` — For Log Analytics queries
14> - `azure-monitor-query-metrics` — For metrics queries
15>
16> See migration guides: [Logs Migration](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query-logs/migration-guide.md) | [Metrics Migration](https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query-metrics/migration-guide.md)
17 
18Client library for querying Azure Monitor Logs and Metrics.
19 
20## Installation
21 
22```xml
23<dependency>
24    <groupId>com.azure</groupId>
25    <artifactId>azure-monitor-query</artifactId>
26    <version>1.5.9</version>
27</dependency>
28```
29 
30Or use Azure SDK BOM:
31 
32```xml
33<dependencyManagement>
34    <dependencies>
35        <dependency>
36            <groupId>com.azure</groupId>
37            <artifactId>azure-sdk-bom</artifactId>
38            <version>{bom_version}</version>
39            <type>pom</type>
40            <scope>import</scope>
41        </dependency>
42    </dependencies>
43</dependencyManagement>
44 
45<dependencies>
46    <dependency>
47        <groupId>com.azure</groupId>
48        <artifactId>azure-monitor-query</artifactId>
49    </dependency>
50</dependencies>
51```
52 
53## Prerequisites
54 
55- Log Analytics workspace (for logs queries)
56- Azure resource (for metrics queries)
57- TokenCredential with appropriate permissions
58 
59## Environment Variables
60 
61```bash
62LOG_ANALYTICS_WORKSPACE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
63AZURE_RESOURCE_ID=/subscriptions/{sub}/resourceGroups/{rg}/providers/{provider}/{resource}
64```
65 
66## Client Creation
67 
68### LogsQueryClient (Sync)
69 
70```java
71import com.azure.identity.DefaultAzureCredentialBuilder;
72import com.azure.monitor.query.LogsQueryClient;
73import com.azure.monitor.query.LogsQueryClientBuilder;
74 
75LogsQueryClient logsClient = new LogsQueryClientBuilder()
76    .credential(new DefaultAzureCredentialBuilder().build())
77    .buildClient();
78```
79 
80### LogsQueryAsyncClient
81 
82```java
83import com.azure.monitor.query.LogsQueryAsyncClient;
84 
85LogsQueryAsyncClient logsAsyncClient = new LogsQueryClientBuilder()
86    .credential(new DefaultAzureCredentialBuilder().build())
87    .buildAsyncClient();
88```
89 
90### MetricsQueryClient (Sync)
91 
92```java
93import com.azure.monitor.query.MetricsQueryClient;
94import com.azure.monitor.query.MetricsQueryClientBuilder;
95 
96MetricsQueryClient metricsClient = new MetricsQueryClientBuilder()
97    .credential(new DefaultAzureCredentialBuilder().build())
98    .buildClient();
99```
100 
101### MetricsQueryAsyncClient
102 
103```java
104import com.azure.monitor.query.MetricsQueryAsyncClient;
105 
106MetricsQueryAsyncClient metricsAsyncClient = new MetricsQueryClientBuilder()
107    .credential(new DefaultAzureCredentialBuilder().build())
108    .buildAsyncClient();
109```
110 
111### Sovereign Cloud Configuration
112 
113```java
114// Azure China Cloud - Logs
115LogsQueryClient logsClient = new LogsQueryClientBuilder()
116    .credential(new DefaultAzureCredentialBuilder().build())
117    .endpoint("https://api.loganalytics.azure.cn/v1")
118    .buildClient();
119 
120// Azure China Cloud - Metrics
121MetricsQueryClient metricsClient = new MetricsQueryClientBuilder()
122    .credential(new DefaultAzureCredentialBuilder().build())
123    .endpoint("https://management.chinacloudapi.cn")
124    .buildClient();
125```
126 
127## Key Concepts
128 
129| Concept | Description |
130|---------|-------------|
131| Logs | Log and performance data from Azure resources via Kusto Query Language |
132| Metrics | Numeric time-series data collected at regular intervals |
133| Workspace ID | Log Analytics workspace identifier |
134| Resource ID | Azure resource URI for metrics queries |
135| QueryTimeInterval | Time range for the query |
136 
137## Logs Query Operations
138 
139### Basic Query
140 
141```java
142import com.azure.monitor.query.models.LogsQueryResult;
143import com.azure.monitor.query.models.LogsTableRow;
144import com.azure.monitor.query.models.QueryTimeInterval;
145import java.time.Duration;
146 
147LogsQueryResult result = logsClient.queryWorkspace(
148    "{workspace-id}",
149    "AzureActivity | summarize count() by ResourceGroup | top 10 by count_",
150    new QueryTimeInterval(Duration.ofDays(7))
151);
152 
153for (LogsTableRow row : result.getTable().getRows()) {
154    System.out.println(row.getColumnValue("ResourceGroup") + ": " + row.getColumnValue("count_"));
155}
156```
157 
158### Query by Resource ID
159 
160```java
161LogsQueryResult result = logsClient.queryResource(
162    "{resource-id}",
163    "AzureMetrics | where TimeGenerated > ago(1h)",
164    new QueryTimeInterval(Duration.ofDays(1))
165);
166 
167for (LogsTableRow row : result.getTable().getRows()) {
168    System.out.println(row.getColumnValue("MetricName") + " " + row.getColumnValue("Average"));
169}
170```
171 
172### Map Results to Custom Model
173 
174```java
175// Define model class
176public class ActivityLog {
177    private String resourceGroup;
178    private String operationName;
179    
180    public String getResourceGroup() { return resourceGroup; }
181    public String getOperationName() { return operationName; }
182}
183 
184// Query with model mapping
185List<ActivityLog> logs = logsClient.queryWorkspace(
186    "{workspace-id}",
187    "AzureActivity | project ResourceGroup, OperationName | take 100",
188    new QueryTimeInterval(Duration.ofDays(2)),
189    ActivityLog.class
190);
191 
192for (ActivityLog log : logs) {
193    System.out.println(log.getOperationName() + " - " + log.getResourceGroup());
194}
195```
196 
197### Batch Query
198 
199```java
200import com.azure.monitor.query.models.LogsBatchQuery;
201import com.azure.monitor.query.models.LogsBatchQueryResult;
202import com.azure.monitor.query.models.LogsBatchQueryResultCollection;
203import com.azure.core.util.Context;
204 
205LogsBatchQuery batchQuery = new LogsBatchQuery();
206String q1 = batchQuery.addWorkspaceQuery("{workspace-id}", "AzureActivity | count", new QueryTimeInterval(Duration.ofDays(1)));
207String q2 = batchQuery.addWorkspaceQuery("{workspace-id}", "Heartbeat | count", new QueryTimeInterval(Duration.ofDays(1)));
208String q3 = batchQuery.addWorkspaceQuery("{workspace-id}", "Perf | count", new QueryTimeInterval(Duration.ofDays(1)));
209 
210LogsBatchQueryResultCollection results = logsClient
211    .queryBatchWithResponse(batchQuery, Context.NONE)
212    .getValue();
213 
214LogsBatchQueryResult result1 = results.getResult(q1);
215LogsBatchQueryResult result2 = results.getResult(q2);
216LogsBatchQueryResult result3 = results.getResult(q3);
217 
218// Check for failures
219if (result3.getQueryResultStatus() == LogsQueryResultStatus.FAILURE) {
220    System.err.println("Query failed: " + result3.getError().getMessage());
221}
222```
223 
224### Query with Options
225 
226```java
227import com.azure.monitor.query.models.LogsQueryOptions;
228import com.azure.core.http.rest.Response;
229 
230LogsQueryOptions options = new LogsQueryOptions()
231    .setServerTimeout(Duration.ofMinutes(10))
232    .setIncludeStatistics(true)
233    .setIncludeVisualization(true);
234 
235Response<LogsQueryResult> response = logsClient.queryWorkspaceWithResponse(
236    "{workspace-id}",
237    "AzureActivity | summarize count() by bin(TimeGenerated, 1h)",
238    new QueryTimeInterval(Duration.ofDays(7)),
239    options,
240    Context.NONE
241);
242 
243LogsQueryResult result = response.getValue();
244 
245// Access statistics
246BinaryData statistics = result.getStatistics();
247// Access visualization data
248BinaryData visualization = result.getVisualization();
249```
250 
251### Query Multiple Workspaces
252 
253```java
254import java.util.Arrays;
255 
256LogsQueryOptions options = new LogsQueryOptions()
257    .setAdditionalWorkspaces(Arrays.asList("{workspace-id-2}", "{workspace-id-3}"));
258 
259Response<LogsQueryResult> response = logsClient.queryWorkspaceWithResponse(
260    "{workspace-id-1}",
261    "AzureActivity | summarize count() by TenantId",
262    new QueryTimeInterval(Duration.ofDays(1)),
263    options,
264    Context.NONE
265);
266```
267 
268## Metrics Query Operations
269 
270### Basic Metrics Query
271 
272```java
273import com.azure.monitor.query.models.MetricsQueryResult;
274import com.azure.monitor.query.models.MetricResult;
275import com.azure.monitor.query.models.TimeSeriesElement;
276import com.azure.monitor.query.models.MetricValue;
277import java.util.Arrays;
278 
279MetricsQueryResult result = metricsClient.queryResource(
280    "{resource-uri}",
281    Arrays.asList("SuccessfulCalls", "TotalCalls")
282);
283 
284for (MetricResult metric : result.getMetrics()) {
285    System.out.println("Metric: " + metric.getMetricName());
286    for (TimeSeriesElement ts : metric.getTimeSeries()) {
287        System.out.println("  Dimensions: " + ts.getMetadata());
288        for (MetricValue value : ts.getValues()) {
289            System.out.println("    " + value.getTimeStamp() + ": " + value.getTotal());
290        }
291    }
292}
293```
294 
295### Metrics with Aggregations
296 
297```java
298import com.azure.monitor.query.models.MetricsQueryOptions;
299import com.azure.monitor.query.models.AggregationType;
300 
301Response<MetricsQueryResult> response = metricsClient.queryResourceWithResponse(
302    "{resource-id}",
303    Arrays.asList("SuccessfulCalls", "TotalCalls"),
304    new MetricsQueryOptions()
305        .setGranularity(Duration.ofHours(1))
306        .setAggregations(Arrays.asList(AggregationType.AVERAGE, AggregationType.COUNT)),
307    Context.NONE
308);
309 
310MetricsQueryResult result = response.getValue();
311```
312 
313### Query Multiple Resources (MetricsClient)
314 
315```java
316import com.azure.monitor.query.MetricsClient;
317import com.azure.monitor.query.MetricsClientBuilder;
318import com.azure.monitor.query.models.MetricsQueryResourcesResult;
319 
320MetricsClient metricsClient = new MetricsClientBuilder()
321    .credential(new DefaultAzureCredentialBuilder().build())
322    .endpoint("{endpoint}")
323    .buildClient();
324 
325MetricsQueryResourcesResult result = metricsClient.queryResources(
326    Arrays.asList("{resourceId1}", "{resourceId2}"),
327    Arrays.asList("{metric1}", "{metric2}"),
328    "{metricNamespace}"
329);
330 
331for (MetricsQueryResult queryResult : result.getMetricsQueryResults()) {
332    for (MetricResult metric : queryResult.getMetrics()) {
333        System.out.println(metric.getMetricName());
334        metric.getTimeSeries().stream()
335            .flatMap(ts -> ts.getValues().stream())
336            .forEach(mv -> System.out.println(
337                mv.getTimeStamp() + " Count=" + mv.getCount() + " Avg=" + mv.getAverage()));
338    }
339}
340```
341 
342## Response Structure
343 
344### Logs Response Hierarchy
345 
346```
347LogsQueryResult
348├── statistics (BinaryData)
349├── visualization (BinaryData)
350├── error
351└── tables (List<LogsTable>)
352    ├── name
353    ├── columns (List<LogsTableColumn>)
354    │   ├── name
355    │   └── type
356    └── rows (List<LogsTableRow>)
357        ├── rowIndex
358        └── rowCells (List<LogsTableCell>)
359```
360 
361### Metrics Response Hierarchy
362 
363```
364MetricsQueryResult
365├── granularity
366├── timeInterval
367├── namespace
368├── resourceRegion
369└── metrics (List<MetricResult>)
370    ├── id, name, type, unit
371    └── timeSeries (List<TimeSeriesElement>)
372        ├── metadata (dimensions)
373        └── values (List<MetricValue>)
374            ├── timeStamp
375            ├── count, average, total
376            ├── maximum, minimum
377```
378 
379## Error Handling
380 
381```java
382import com.azure.core.exception.HttpResponseException;
383import com.azure.monitor.query.models.LogsQueryResultStatus;
384 
385try {
386    LogsQueryResult result = logsClient.queryWorkspace(workspaceId, query, timeInterval);
387    
388    // Check partial failure
389    if (result.getStatus() == LogsQueryResultStatus.PARTIAL_FAILURE) {
390        System.err.println("Partial failure: " + result.getError().getMessage());
391    }
392} catch (HttpResponseException e) {
393    System.err.println("Query failed: " + e.getMessage());
394    System.err.println("Status: " + e.getResponse().getStatusCode());
395}
396```
397 
398## Best Practices
399 
4001. **Use batch queries** — Combine multiple queries into a single request
4012. **Set appropriate timeouts** — Long queries may need extended server timeout
4023. **Limit result size** — Use `top` or `take` in Kusto queries
4034. **Use projections** — Select only needed columns with `project`
4045. **Check query status** — Handle PARTIAL_FAILURE results gracefully
4056. **Cache results** — Metrics don't change frequently; cache when appropriate
4067. **Migrate to new packages** — Plan migration to `azure-monitor-query-logs` and `azure-monitor-query-metrics`
407 
408## Reference Links
409 
410| Resource | URL |
411|----------|-----|
412| Maven Package | https://central.sonatype.com/artifact/com.azure/azure-monitor-query |
413| GitHub | https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/monitor/azure-monitor-query |
414| API Reference | https://learn.microsoft.com/java/api/com.azure.monitor.query |
415| Kusto Query Language | https://learn.microsoft.com/azure/data-explorer/kusto/query/ |
416| Log Analytics Limits | https://learn.microsoft.com/azure/azure-monitor/service-limits#la-query-api |
417| Troubleshooting | https://github.com/Azure/azure-sdk-for-java/blob/main/sdk/monitor/azure-monitor-query/TROUBLESHOOTING.md |
418