Azure Monitor Query SDK for Java
DEPRECATION NOTICE: This package is deprecated in favor of:
azure-monitor-query-logs— For Log Analytics queriesazure-monitor-query-metrics— For metrics queriesSee migration guides: Logs Migration | Metrics Migration
Client library for querying Azure Monitor Logs and Metrics.
Installation
xml
<dependency> <groupId>com.azure</groupId> <artifactId>azure-monitor-query</artifactId> <version>1.5.9</version></dependency>Or use Azure SDK BOM:
xml
<dependencyManagement> <dependencies> <dependency> <groupId>com.azure</groupId> <artifactId>azure-sdk-bom</artifactId> <version>{bom_version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies></dependencyManagement>
<dependencies> <dependency> <groupId>com.azure</groupId> <artifactId>azure-monitor-query</artifactId> </dependency></dependencies>Prerequisites
- Log Analytics workspace (for logs queries)
- Azure resource (for metrics queries)
- TokenCredential with appropriate permissions
Environment Variables
bash
LOG_ANALYTICS_WORKSPACE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx # Required for Log Analytics workspace queriesAZURE_RESOURCE_ID=/subscriptions/{sub}/resourceGroups/{rg}/providers/{provider}/{resource} # Required for metrics queries against a resourceAZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in productionClient Creation
LogsQueryClient (Sync)
java
import com.azure.core.credential.TokenCredential;import com.azure.identity.AzureIdentityEnvVars;import com.azure.identity.DefaultAzureCredentialBuilder;import com.azure.identity.ManagedIdentityCredentialBuilder;import com.azure.monitor.query.LogsQueryClient;import com.azure.monitor.query.LogsQueryClientBuilder;
// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>TokenCredential credential = new DefaultAzureCredentialBuilder() .requireEnvVars(AzureIdentityEnvVars.AZURE_TOKEN_CREDENTIALS) .build();// Or use a specific credential directly in production:// See https://learn.microsoft.com/java/api/overview/azure/identity-readme?view=azure-java-stable#credential-classes// TokenCredential credential = new ManagedIdentityCredentialBuilder().build();
LogsQueryClient logsClient = new LogsQueryClientBuilder() .credential(credential) .buildClient();LogsQueryAsyncClient
java
import com.azure.monitor.query.LogsQueryAsyncClient;
LogsQueryAsyncClient logsAsyncClient = new LogsQueryClientBuilder() .credential(credential) .buildAsyncClient();MetricsQueryClient (Sync)
java
import com.azure.monitor.query.MetricsQueryClient;import com.azure.monitor.query.MetricsQueryClientBuilder;
MetricsQueryClient metricsClient = new MetricsQueryClientBuilder() .credential(credential) .buildClient();MetricsQueryAsyncClient
java
import com.azure.monitor.query.MetricsQueryAsyncClient;
MetricsQueryAsyncClient metricsAsyncClient = new MetricsQueryClientBuilder() .credential(credential) .buildAsyncClient();Sovereign Cloud Configuration
java
// Azure China Cloud - LogsLogsQueryClient logsClient = new LogsQueryClientBuilder() .credential(credential) .endpoint("https://api.loganalytics.azure.cn/v1") .buildClient();
// Azure China Cloud - MetricsMetricsQueryClient metricsClient = new MetricsQueryClientBuilder() .credential(credential) .endpoint("https://management.chinacloudapi.cn") .buildClient();Key Concepts
| Concept | Description |
|---|---|
| Logs | Log and performance data from Azure resources via Kusto Query Language |
| Metrics | Numeric time-series data collected at regular intervals |
| Workspace ID | Log Analytics workspace identifier |
| Resource ID | Azure resource URI for metrics queries |
| QueryTimeInterval | Time range for the query |
Logs Query Operations
Basic Query
java
import com.azure.monitor.query.models.LogsQueryResult;import com.azure.monitor.query.models.LogsTableRow;import com.azure.monitor.query.models.QueryTimeInterval;import java.time.Duration;
LogsQueryResult result = logsClient.queryWorkspace( "{workspace-id}", "AzureActivity | summarize count() by ResourceGroup | top 10 by count_", new QueryTimeInterval(Duration.ofDays(7)));
for (LogsTableRow row : result.getTable().getRows()) { System.out.println(row.getColumnValue("ResourceGroup") + ": " + row.getColumnValue("count_"));}Query by Resource ID
java
LogsQueryResult result = logsClient.queryResource( "{resource-id}", "AzureMetrics | where TimeGenerated > ago(1h)", new QueryTimeInterval(Duration.ofDays(1)));
for (LogsTableRow row : result.getTable().getRows()) { System.out.println(row.getColumnValue("MetricName") + " " + row.getColumnValue("Average"));}Map Results to Custom Model
java
// Define model classpublic class ActivityLog { private String resourceGroup; private String operationName; public String getResourceGroup() { return resourceGroup; } public String getOperationName() { return operationName; }}
// Query with model mappingList<ActivityLog> logs = logsClient.queryWorkspace( "{workspace-id}", "AzureActivity | project ResourceGroup, OperationName | take 100", new QueryTimeInterval(Duration.ofDays(2)), ActivityLog.class);
for (ActivityLog log : logs) { System.out.println(log.getOperationName() + " - " + log.getResourceGroup());}Batch Query
java
import com.azure.monitor.query.models.LogsBatchQuery;import com.azure.monitor.query.models.LogsBatchQueryResult;import com.azure.monitor.query.models.LogsBatchQueryResultCollection;import com.azure.core.util.Context;
LogsBatchQuery batchQuery = new LogsBatchQuery();String q1 = batchQuery.addWorkspaceQuery("{workspace-id}", "AzureActivity | count", new QueryTimeInterval(Duration.ofDays(1)));String q2 = batchQuery.addWorkspaceQuery("{workspace-id}", "Heartbeat | count", new QueryTimeInterval(Duration.ofDays(1)));String q3 = batchQuery.addWorkspaceQuery("{workspace-id}", "Perf | count", new QueryTimeInterval(Duration.ofDays(1)));
LogsBatchQueryResultCollection results = logsClient .queryBatchWithResponse(batchQuery, Context.NONE) .getValue();
LogsBatchQueryResult result1 = results.getResult(q1);LogsBatchQueryResult result2 = results.getResult(q2);LogsBatchQueryResult result3 = results.getResult(q3);
// Check for failuresif (result3.getQueryResultStatus() == LogsQueryResultStatus.FAILURE) { System.err.println("Query failed: " + result3.getError().getMessage());}Query with Options
java
import com.azure.monitor.query.models.LogsQueryOptions;import com.azure.core.http.rest.Response;
LogsQueryOptions options = new LogsQueryOptions() .setServerTimeout(Duration.ofMinutes(10)) .setIncludeStatistics(true) .setIncludeVisualization(true);
Response<LogsQueryResult> response = logsClient.queryWorkspaceWithResponse( "{workspace-id}", "AzureActivity | summarize count() by bin(TimeGenerated, 1h)", new QueryTimeInterval(Duration.ofDays(7)), options, Context.NONE);
LogsQueryResult result = response.getValue();
// Access statisticsBinaryData statistics = result.getStatistics();// Access visualization dataBinaryData visualization = result.getVisualization();Query Multiple Workspaces
java
import java.util.Arrays;
LogsQueryOptions options = new LogsQueryOptions() .setAdditionalWorkspaces(Arrays.asList("{workspace-id-2}", "{workspace-id-3}"));
Response<LogsQueryResult> response = logsClient.queryWorkspaceWithResponse( "{workspace-id-1}", "AzureActivity | summarize count() by TenantId", new QueryTimeInterval(Duration.ofDays(1)), options, Context.NONE);Metrics Query Operations
Basic Metrics Query
java
import com.azure.monitor.query.models.MetricsQueryResult;import com.azure.monitor.query.models.MetricResult;import com.azure.monitor.query.models.TimeSeriesElement;import com.azure.monitor.query.models.MetricValue;import java.util.Arrays;
MetricsQueryResult result = metricsClient.queryResource( "{resource-uri}", Arrays.asList("SuccessfulCalls", "TotalCalls"));
for (MetricResult metric : result.getMetrics()) { System.out.println("Metric: " + metric.getMetricName()); for (TimeSeriesElement ts : metric.getTimeSeries()) { System.out.println(" Dimensions: " + ts.getMetadata()); for (MetricValue value : ts.getValues()) { System.out.println(" " + value.getTimeStamp() + ": " + value.getTotal()); } }}Metrics with Aggregations
java
import com.azure.monitor.query.models.MetricsQueryOptions;import com.azure.monitor.query.models.AggregationType;
Response<MetricsQueryResult> response = metricsClient.queryResourceWithResponse( "{resource-id}", Arrays.asList("SuccessfulCalls", "TotalCalls"), new MetricsQueryOptions() .setGranularity(Duration.ofHours(1)) .setAggregations(Arrays.asList(AggregationType.AVERAGE, AggregationType.COUNT)), Context.NONE);
MetricsQueryResult result = response.getValue();Query Multiple Resources (MetricsClient)
java
import com.azure.monitor.query.MetricsClient;import com.azure.monitor.query.MetricsClientBuilder;import com.azure.monitor.query.models.MetricsQueryResourcesResult;
MetricsClient metricsClient = new MetricsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) .endpoint("{endpoint}") .buildClient();
MetricsQueryResourcesResult result = metricsClient.queryResources( Arrays.asList("{resourceId1}", "{resourceId2}"), Arrays.asList("{metric1}", "{metric2}"), "{metricNamespace}");
for (MetricsQueryResult queryResult : result.getMetricsQueryResults()) { for (MetricResult metric : queryResult.getMetrics()) { System.out.println(metric.getMetricName()); metric.getTimeSeries().stream() .flatMap(ts -> ts.getValues().stream()) .forEach(mv -> System.out.println( mv.getTimeStamp() + " Count=" + mv.getCount() + " Avg=" + mv.getAverage())); }}Response Structure
Logs Response Hierarchy
LogsQueryResult├── statistics (BinaryData)├── visualization (BinaryData)├── error└── tables (List<LogsTable>) ├── name ├── columns (List<LogsTableColumn>) │ ├── name │ └── type └── rows (List<LogsTableRow>) ├── rowIndex └── rowCells (List<LogsTableCell>)Metrics Response Hierarchy
MetricsQueryResult├── granularity├── timeInterval├── namespace├── resourceRegion└── metrics (List<MetricResult>) ├── id, name, type, unit └── timeSeries (List<TimeSeriesElement>) ├── metadata (dimensions) └── values (List<MetricValue>) ├── timeStamp ├── count, average, total ├── maximum, minimumError Handling
java
import com.azure.core.exception.HttpResponseException;import com.azure.monitor.query.models.LogsQueryResultStatus;
try { LogsQueryResult result = logsClient.queryWorkspace(workspaceId, query, timeInterval); // Check partial failure if (result.getStatus() == LogsQueryResultStatus.PARTIAL_FAILURE) { System.err.println("Partial failure: " + result.getError().getMessage()); }} catch (HttpResponseException e) { System.err.println("Query failed: " + e.getMessage()); System.err.println("Status: " + e.getResponse().getStatusCode());}Best Practices
- Use batch queries — Combine multiple queries into a single request
- Set appropriate timeouts — Long queries may need extended server timeout
- Limit result size — Use
toportakein Kusto queries - Use projections — Select only needed columns with
project - Check query status — Handle PARTIAL_FAILURE results gracefully
- Cache results — Metrics don't change frequently; cache when appropriate
- Migrate to new packages — Plan migration to
azure-monitor-query-logsandazure-monitor-query-metrics


