Azure Monitor Query Java

作者 microsoft354361d83247MIT收录于 2026年10月8日更新于 2026年10月8日

Azure Monitor Query SDK for Java. Execute Kusto queries against Log Analytics workspaces and query metrics from Azure resources. Triggers: "LogsQueryClient java", "MetricsQueryClient java", "kusto query java", "log analytics java", "azure monitor query java". Note: This package is deprecated. Migrate to azure-monitor-query-logs and azure-monitor-query-metrics.

AI 生成的概览

指导 Java 开发者使用已弃用的 Azure Monitor Query SDK 执行 Kusto 日志查询并获取 Azure 资源指标。

功能
提供 Azure Monitor Query Java SDK 的参考说明与代码示例,涵盖日志与指标客户端创建、工作区和资源查询、批量查询、模型映射、聚合、主权云终结点、响应结构和错误处理。同时说明该包已弃用并指向迁移指南。产出为指引和代码片段,而非可执行产物。
适用场景
适用于编写或审查使用 com.azure:azure-monitor-query 包查询 Azure Monitor 日志或指标的 Java 代码。也适合规划从该弃用包迁移时使用。
运行要求
需要 Java 及 Maven 或 Azure SDK BOM、com.azure:azure-monitor-query 依赖、具有相应权限的 TokenCredential、Log Analytics 工作区 ID 或 Azure 资源 ID,以及访问 Azure Monitor 终结点的网络连接。不包含脚本。

Azure Monitor Query SDK for Java

DEPRECATION NOTICE: This package is deprecated in favor of:

  • azure-monitor-query-logs — For Log Analytics queries
  • azure-monitor-query-metrics — For metrics queries

See 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 production

Client 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

ConceptDescription
LogsLog and performance data from Azure resources via Kusto Query Language
MetricsNumeric time-series data collected at regular intervals
Workspace IDLog Analytics workspace identifier
Resource IDAzure resource URI for metrics queries
QueryTimeIntervalTime 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, minimum

Error 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

  1. Use batch queries — Combine multiple queries into a single request
  2. Set appropriate timeouts — Long queries may need extended server timeout
  3. Limit result size — Use top or take in Kusto queries
  4. Use projections — Select only needed columns with project
  5. Check query status — Handle PARTIAL_FAILURE results gracefully
  6. Cache results — Metrics don't change frequently; cache when appropriate
  7. Migrate to new packages — Plan migration to azure-monitor-query-logs and azure-monitor-query-metrics

Reference Links

来源与署名

来源:microsoft/skills位于.github/plugins/azure-sdk-java/skills/azure-monitor-query-java提交354361d

许可证: MIT

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架