See: Description
Package | Description |
---|---|
com.azure.monitor.query |
Package containing clients for querying logs and metrics from Azure Monitor.
|
com.azure.monitor.query.models |
Package containing models for querying logs and metrics from Azure Monitor.
|
Azure Monitor helps you maximize the availability and performance of your applications and services. It delivers a comprehensive solution for collecting, analyzing, and acting on telemetry from your cloud and on-premises environments.
All data collected by Azure Monitor fits into one of two fundamental types, metrics and logs. Metrics are numerical values that describe some aspect of a system at a particular point in time. They are lightweight and capable of supporting near real-time scenarios. Logs contain different kinds of data organized into records with different sets of properties for each type. Telemetry such as events and traces are stored as logs in addition to performance data so that it can all be combined for analysis.
This client library provides access to query metrics and logs collected by Azure Monitor.
Source code | Product Documentation | Samples
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-monitor-query</artifactId>
<version>1.0.0-beta.4</version>
</dependency>
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
LogsQueryAsyncClient logsQueryAsyncClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildAsyncClient();
MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
MetricsQueryAsyncClient metricsQueryAsyncClient = new MetricsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildAsyncClient();
Azure Monitor Logs is a feature of Azure Monitor that collects and organizes log and performance data from monitored resources. Data from different sources such as platform logs from Azure services, log and performance data from virtual machines agents, and usage and performance data from applications can be consolidated into a single workspace so they can be analyzed together using a sophisticated query language that's capable of quickly analyzing millions of records. You may perform a simple query that just retrieves a specific set of records or perform sophisticated data analysis to identify critical patterns in your monitoring data.
Data collected by Azure Monitor Logs is stored in one or more Log Analytics workspaces. The workspace defines the geographic location of the data, access rights defining which users can access data, and configuration settings such as the pricing tier and data retention.
You must create at least one workspace to use Azure Monitor Logs. A single workspace may be sufficient for all of your monitoring data, or may choose to create multiple workspaces depending on your requirements. For example, you might have one workspace for your production data and another for testing.
Data is retrieved from a Log Analytics workspace using a log query which is a read-only request to process data and return results. Log queries are written in Kusto Query Language (KQL), which is the same query language used by Azure Data Explorer. You can write log queries in Log Analytics to interactively analyze their results, use them in alert rules to be proactively notified of issues, or include their results in workbooks or dashboards. Insights include prebuilt queries to support their views and workbooks.
Each AAD user is able to make up to 200 requests per 30 seconds, with no cap on the total calls per day.If requests are
being made at a rate higher than this, then these requests will receive HTTP status code 429
(Too Many Requests) along with the Retry-After:
As well as call rate limits and daily quota caps, there are also limits on queries themselves:
Azure Monitor Metrics is a feature of Azure Monitor that collects numeric data from monitored resources into a time series database. Metrics are numerical values that are collected at regular intervals and describe some aspect of a system at a particular time. Metrics in Azure Monitor are lightweight and capable of supporting near real-time scenarios making them particularly useful for alerting and fast detection of issues. You can analyze them interactively with metrics explorer, be proactively notified with an alert when a value crosses a threshold, or visualize them in a workbook or dashboard.
Data collected by Azure Monitor Metrics is stored in a time-series database which is optimized for analyzing time-stamped data. Each set of metric values is a time series with the following properties:
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
LogsQueryResult queryResults = logsQueryClient.query("{workspace-id}", "{kusto-query}",
new TimeInterval(Duration.ofDays(2)));
for (LogsTableRow row : queryResults.getTable().getRows()) {
System.out.println(row.getColumnValue("OperationName") + " " + row.getColumnValue("ResourceGroup"));
}
public class CustomLogModel {
private String resourceGroup;
private String operationName;
public String getResourceGroup() {
return resourceGroup;
}
public String getOperationName() {
return operationName;
}
}
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
List<CustomLogModel> customLogModels = logsQueryClient.query("{workspace-id}", "{kusto-query}",
new TimeInterval(Duration.ofDays(2)), CustomLogModel.class);
for (CustomLogModel customLogModel : customLogModels) {
System.out.println(customLogModel.getOperationName() + " " + customLogModel.getResourceGroup());
}
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
LogsBatchQuery logsBatchQuery = new LogsBatchQuery();
String query1 = logsBatchQuery.addQuery("{workspace-id}", "{query-1}", new TimeInterval(Duration.ofDays(2)));
String query2 = logsBatchQuery.addQuery("{workspace-id}", "{query-2}", new TimeInterval(Duration.ofDays(30)));
String query3 = logsBatchQuery.addQuery("{workspace-id}", "{query-3}", new TimeInterval(Duration.ofDays(10)));
LogsBatchQueryResultCollection batchResults = logsQueryClient
.queryBatchWithResponse(logsBatchQuery, Context.NONE).getValue();
LogsBatchQueryResult query1Result = batchResults.getResult(query1);
for (LogsTableRow row : query1Result.getTable().getRows()) {
System.out.println(row.getColumnValue("OperationName") + " " + row.getColumnValue("ResourceGroup"));
}
List<CustomLogModel> customLogModels = batchResults.getResult(query2, CustomLogModel.class);
for (CustomLogModel customLogModel : customLogModels) {
System.out.println(customLogModel.getOperationName() + " " + customLogModel.getResourceGroup());
}
LogsBatchQueryResult query3Result = batchResults.getResult(query3);
if (query3Result.hasFailed()) {
System.out.println(query3Result.getError().getMessage());
}
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
// set request options: server timeout
LogsQueryOptions options = new LogsQueryOptions()
.setServerTimeout(Duration.ofMinutes(10));
Response<LogsQueryResult> response = logsQueryClient.queryWithResponse("{workspace-id}",
"{kusto-query}", new TimeInterval(Duration.ofDays(2)), options, Context.NONE);
When multiple workspaces are included in the query, the logs in the result table are not grouped according to the workspace from which it was retrieved. To identify the workspace of a row in the result table, you can inspect the "TenantId" column in the result table. If this column is not in the table, then you may have to update your query string to include this column.
LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
Response<LogsQueryResult> response = logsQueryClient.queryWithResponse("{workspace-id}", "{kusto-query}",
new TimeInterval(Duration.ofDays(2)), new LogsQueryOptions()
.setAdditionalWorkspaces(Arrays.asList("{additional-workspace-identifiers}")),
Context.NONE);
LogsQueryResult result = response.getValue();
The query
API returns the LogsQueryResult
while the queryBatch
API returns the LogsBatchQueryResult
.
Here is a hierarchy of the response:
LogsQueryResult / LogsBatchQueryResult
|---id (this exists in `LogsBatchQueryResult` object only)
|---status (this exists in `LogsBatchQueryResult` object only)
|---statistics
|---visualization
|---error
|---tables (list of `LogsTable` objects)
|---name
|---rows (list of `LogsTableRow` objects)
|--- rowIndex
|--- rowCells (list of `LogsTableCell` objects)
|---columns (list of `LogsTableColumn` objects)
|---name
|---type
A resource ID, as denoted by the {resource-id}
placeholder in the sample below, is required to query metrics. To find the resource ID:
id
property.MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
MetricsQueryResult metricsQueryResult = metricsQueryClient.query("{resource-uri}",
Arrays.asList("SuccessfulCalls", "TotalCalls"));
for (MetricResult metric : metricsQueryResult.getMetrics()) {
System.out.println("Metric name " + metric.getMetricName());
for (TimeSeriesElement timeSeriesElement : metric.getTimeSeries()) {
System.out.println("Dimensions " + timeSeriesElement.getMetadata());
for (MetricValue metricValue : timeSeriesElement.getValues()) {
System.out.println(metricValue.getTimeStamp() + " " + metricValue.getTotal());
}
}
}
MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
Response<MetricsQueryResult> metricsResponse = metricsQueryClient
.queryWithResponse("{resource-id}", Arrays.asList("SuccessfulCalls", "TotalCalls"),
new MetricsQueryOptions()
.setGranularity(Duration.ofHours(1))
.setAggregations(Arrays.asList(AggregationType.AVERAGE, AggregationType.COUNT)),
Context.NONE);
MetricsQueryResult metricsQueryResult = metricsResponse.getValue();
for (MetricResult metric : metricsQueryResult.getMetrics()) {
System.out.println("Metric name " + metric.getMetricName());
for (TimeSeriesElement timeSeriesElement : metric.getTimeSeries()) {
System.out.println("Dimensions " + timeSeriesElement.getMetadata());
for (MetricValue metricValue : timeSeriesElement.getValues()) {
System.out.println(metricValue.getTimeStamp() + " " + metricValue.getTotal());
}
}
}
The metrics query API returns a MetricsQueryResult
object. The MetricsQueryResult
object contains properties such as a
list of MetricResult
-typed objects, granularity
, namespace
, and timeInterval
. The MetricResult
objects list
can be accessed using the metrics
param. Each MetricResult
object in this list contains a list of TimeSeriesElement
objects.
Each TimeSeriesElement
contains data
and metadata_values
properties. The MetricResult
list is ordered
according to the list of metrics names provided in the request. In visual form, the object hierarchy of the
response resembles the following structure:
|---granularity
|---timeInterval
|---cost
|---namespace
|---resourceRegion
|---metrics (list of `MetricResult` objects)
|---id
|---type
|---name
|---unit
|---timeSeries (list of `TimeSeriesElement` objects)
|---metadata (dimensions)
|---metricValues (list of data points represented by `MetricValue` objects)
|--- timeStamp
|--- count
|--- average
|--- total
|--- maximum
|--- minimum
You can set the AZURE_LOG_LEVEL
environment variable to view logging statements made in the client library. For
example, setting AZURE_LOG_LEVEL=2
would show all informational, warning, and error log messages. The log levels can
be found here: log levels.
All client libraries by default use the Netty HTTP client. Adding the above dependency will automatically configure the client library to use the Netty HTTP client. Configuring or changing the HTTP client is detailed in the HTTP clients wiki.
All client libraries, by default, use the Tomcat-native Boring SSL library to enable native-level performance for SSL operations. The Boring SSL library is an uber jar containing native libraries for Linux / macOS / Windows, and provides better performance compared to the default SSL com.azure.monitor.collect.metrics.implementation within the JDK. For more information, including how to reduce the dependency size, refer to the performance tuning section of the wiki.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Copyright © 2021 Microsoft Corporation. All rights reserved.