Biblioteca cliente de consultas de Azure Monitor para Java: versión 1.2.6

Artículo
10/25/2023

La biblioteca cliente de consultas de Azure Monitor se usa para ejecutar consultas de solo lectura en las dos plataformas de datos de Azure Monitor:

Registros : recopila y organiza los datos de registro y rendimiento de los recursos supervisados. Los datos de diferentes orígenes, como los registros de plataforma de los servicios de Azure, los datos de registro y rendimiento de los agentes de máquinas virtuales, y los datos de uso y rendimiento de las aplicaciones se pueden consolidar en un único área de trabajo de Azure Log Analytics. Los distintos tipos de datos se pueden analizar conjuntamente mediante el Lenguaje de consulta Kusto.
Métricas : recopila datos numéricos de recursos supervisados en una base de datos de serie temporal. Las métricas son valores numéricos que se recopilan a intervalos regulares y describen algún aspecto de un sistema en un momento determinado. Las métricas son ligeras y capaces de admitir escenarios casi en tiempo real, lo que hace que sean especialmente útiles para alertas y detección rápida de problemas.

Recursos:

Introducción

Requisitos previos

Un kit de desarrollo de Java (JDK), versión 8 o posterior.
Una suscripción de Azure
Una implementación de TokenCredential, como un tipo de credencial de la biblioteca de Azure Identity.
Para consultar los registros, necesita un área de trabajo de Azure Log Analytics o un recurso de Azure de cualquier tipo (cuenta de almacenamiento, Key Vault, Cosmos DB, etc.).
Para consultar métricas, necesita un recurso de Azure de cualquier tipo (cuenta de almacenamiento, Key Vault, Cosmos DB, etc.).

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte EL ARCHIVO LÉAME BOM del SDK de AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

y, a continuación, incluya la dependencia directa en la sección dependencias sin la etiqueta de versión, como se muestra a continuación.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-query</artifactId>
  </dependency>
</dependencies>

Inclusión de dependencias directas

Si quiere depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-query</artifactId>
    <version>1.2.6</version>
</dependency>

Creación del cliente

Se requiere un cliente autenticado para consultar registros o métricas. La biblioteca incluye formas sincrónicas y asincrónicas de los clientes. Para autenticarse, en los ejemplos siguientes se usa DefaultAzureCredentialBuilder el paquete azure-identity .

Autenticación mediante Azure Active Directory

Puede autenticarse con Azure Active Directory mediante la biblioteca de identidades de Azure. Tenga en cuenta que los puntos de conexión regionales no admiten la autenticación de AAD. Cree un subdominio personalizado para el recurso con el fin de usar este tipo de autenticación.

Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, incluya el azure-identity paquete:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.9.0</version>
</dependency>

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Clientes sincrónicos

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Clientes asincrónicos

LogsQueryAsyncClient logsQueryAsyncClient = new LogsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

MetricsQueryAsyncClient metricsQueryAsyncClient = new MetricsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildAsyncClient();

Configuración de clientes para nubes de Azure no públicas

De forma predeterminada, LogQueryClient y MetricQueryClient están configurados para conectarse a la nube pública de Azure. Estos se pueden configurar para conectarse a nubes de Azure no públicas estableciendo lo correcto endpoint en los generadores de cliente: Por ejemplo:

Creación de un LogsQueryClient para la nube de Azure China:

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint("https://api.loganalytics.azure.cn/v1")
    .buildClient();

Creación de un MetricsQueryClient para la nube de Azure China:

MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .endpoint("https://management.chinacloudapi.cn")
    .buildClient();

Ejecute la consulta.

Para obtener ejemplos de consultas de registros y métricas, consulte la sección Ejemplos .

Conceptos clave

Registra límites y límites de frecuencia de consulta

El servicio Log Analytics aplica una limitación cuando la tasa de solicitudes es demasiado alta. Los límites, como el número máximo de filas devueltas, también se aplican en las consultas de Kusto. Para obtener más información, consulte Query API.

Estructura de datos de métricas

Cada conjunto de valores de métricas es una serie temporal con las siguientes características:

Hora en que se recopiló el valor.
Recurso asociado al valor
Espacio de nombres que actúa como una categoría para la métrica.
Nombre de la métrica.
El propio valor.
Algunas métricas pueden tener varias dimensiones, como se describe en métricas multidimensionales. Las métricas personalizadas pueden tener hasta 10 dimensiones.

Ejemplos

consulta de registros
Consulta de registros por lotes
Escenarios de consulta de registros avanzados
Consulta de métricas

consulta de registros

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

LogsQueryResult queryResults = logsQueryClient.queryWorkspace("{workspace-id}", "{kusto-query}",
        new QueryTimeInterval(Duration.ofDays(2)));

for (LogsTableRow row : queryResults.getTable().getRows()) {
    System.out.println(row.getColumnValue("OperationName") + " " + row.getColumnValue("ResourceGroup"));
}

Asignación de los resultados de la consulta de registros a un modelo

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.queryWorkspace("{workspace-id}", "{kusto-query}",
        new QueryTimeInterval(Duration.ofDays(2)), CustomLogModel.class);

for (CustomLogModel customLogModel : customLogModels) {
    System.out.println(customLogModel.getOperationName() + " " + customLogModel.getResourceGroup());
}

Control de la respuesta de consulta de registros

La query API devuelve LogsQueryResult, mientras que la queryBatch API devuelve .LogsBatchQueryResult Esta es una jerarquía de la respuesta:

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

Consulta de registros por identificador de recurso

LogsQueryClient admite la consulta de registros mediante un identificador de área de trabajo (queryWorkspace métodos) o un identificador de recurso (queryResource métodos). A continuación se muestra un ejemplo de consulta de registros mediante un identificador de recurso. Se pueden aplicar cambios similares a todos los demás ejemplos.

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

LogsQueryResult queryResults = logsQueryClient.queryResource("{resource-id}", "{kusto-query}",
    new QueryTimeInterval(Duration.ofDays(2)));

for (LogsTableRow row : queryResults.getTable().getRows()) {
    System.out.println(row.getColumnValue("OperationName") + " " + row.getColumnValue("ResourceGroup"));
}

Consulta de registros por lotes

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

LogsBatchQuery logsBatchQuery = new LogsBatchQuery();
String query1 = logsBatchQuery.addWorkspaceQuery("{workspace-id}", "{query-1}", new QueryTimeInterval(Duration.ofDays(2)));
String query2 = logsBatchQuery.addWorkspaceQuery("{workspace-id}", "{query-2}", new QueryTimeInterval(Duration.ofDays(30)));
String query3 = logsBatchQuery.addWorkspaceQuery("{workspace-id}", "{query-3}", new QueryTimeInterval(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.getQueryResultStatus() == LogsQueryResultStatus.FAILURE) {
    System.out.println(query3Result.getError().getMessage());
}

Escenarios de consulta de registros avanzados

Establecimiento del tiempo de espera de la consulta de registros

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.queryWorkspaceWithResponse("{workspace-id}",
        "{kusto-query}", new QueryTimeInterval(Duration.ofDays(2)), options, Context.NONE);

Consulta de varias áreas de trabajo

Para ejecutar la misma consulta en varias áreas de trabajo de Log Analytics, use el LogsQueryOptions.setAdditionalWorkspaces método :

Cuando se incluyen varias áreas de trabajo en la consulta, los registros de la tabla de resultados no se agrupan según el área de trabajo desde la que se recuperó. Para identificar el área de trabajo de una fila en la tabla de resultados, puede inspeccionar la columna "TenantId" en la tabla de resultados. Si esta columna no está en la tabla, es posible que tenga que actualizar la cadena de consulta para incluir esta columna.

LogsQueryClient logsQueryClient = new LogsQueryClientBuilder()
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

Response<LogsQueryResult> response = logsQueryClient.queryWorkspaceWithResponse("{workspace-id}", "{kusto-query}",
        new QueryTimeInterval(Duration.ofDays(2)), new LogsQueryOptions()
                .setAdditionalWorkspaces(Arrays.asList("{additional-workspace-identifiers}")),
        Context.NONE);
LogsQueryResult result = response.getValue();

Incluir estadísticas

Para obtener los registros estadísticas de ejecución de consultas, como el consumo de CPU y memoria:

Use LogsQueryOptions para solicitar estadísticas en la respuesta estableciendo setIncludeStatistics() en true.
Invoque el getStatistics método en el LogsQueryResult objeto .

En el ejemplo siguiente se imprime el tiempo de ejecución de la consulta:

LogsQueryClient client = new LogsQueryClientBuilder()
        .credential(credential)
        .buildClient();

LogsQueryOptions options = new LogsQueryOptions()
        .setIncludeStatistics(true);
Response<LogsQueryResult> response = client.queryWorkspaceWithResponse("{workspace-id}",
        "AzureActivity | top 10 by TimeGenerated", QueryTimeInterval.LAST_1_HOUR, options, Context.NONE);
LogsQueryResult result = response.getValue();
BinaryData statistics = result.getStatistics();

ObjectMapper objectMapper = new ObjectMapper();
JsonNode statisticsJson = objectMapper.readTree(statistics.toBytes());
JsonNode queryStatistics = statisticsJson.get("query");
System.out.println("Query execution time = " + queryStatistics.get("executionTime").asDouble());

Dado que la estructura de la carga de estadísticas varía según la consulta, se usa un BinaryData tipo de valor devuelto. Contiene la respuesta JSON sin formato. Las estadísticas se encuentran dentro de la query propiedad de JSON. Por ejemplo:

{
  "query": {
    "executionTime": 0.0156478,
    "resourceUsage": {...},
    "inputDatasetStatistics": {...},
    "datasetStatistics": [{...}]
  }
}

Incluir visualización

Para obtener datos de visualización de consultas de registros mediante el operador render:

Use LogsQueryOptions para solicitar datos de visualización en la respuesta estableciendo setIncludeVisualization() en true.
Invoque el getVisualization método en el LogsQueryResult objeto .

Por ejemplo:

LogsQueryClient client = new LogsQueryClientBuilder()
        .credential(credential)
        .buildClient();

String visualizationQuery = "StormEvents"
        + "| summarize event_count = count() by State"
        + "| where event_count > 10"
        + "| project State, event_count"
        + "| render columnchart";
LogsQueryOptions options = new LogsQueryOptions()
        .setIncludeVisualization(true);
Response<LogsQueryResult> response = client.queryWorkspaceWithResponse("{workspace-id}", visualizationQuery,
        QueryTimeInterval.LAST_7_DAYS, options, Context.NONE);
LogsQueryResult result = response.getValue();
BinaryData visualization = result.getVisualization();

ObjectMapper objectMapper = new ObjectMapper();
JsonNode visualizationJson = objectMapper.readTree(visualization.toBytes());
System.out.println("Visualization graph type = " + visualizationJson.get("visualization").asText());

Dado que la estructura de la carga de visualización varía según la consulta, se usa un BinaryData tipo de valor devuelto. Contiene la respuesta JSON sin formato. Por ejemplo:

{
  "visualization": "columnchart",
  "title": null,
  "accumulate": false,
  "isQuerySorted": false,
  "kind": null,
  "legend": null,
  "series": null,
  "yMin": "",
  "yMax": "",
  "xAxis": null,
  "xColumn": null,
  "xTitle": null,
  "yAxis": null,
  "yColumns": null,
  "ySplit": null,
  "yTitle": null,
  "anomalyColumns": null
}

Consulta de métricas

Se requiere un identificador de recurso, como se indica en el {resource-id} marcador de posición del ejemplo siguiente, para consultar las métricas. Para buscar el identificador de recurso:

Vaya a la página del recurso en el Azure Portal.
En la hoja Información general , seleccione el vínculo Vista JSON .
En el JSON resultante, copie el valor de la id propiedad .

MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
        .credential(new DefaultAzureCredentialBuilder().build())
        .buildClient();

MetricsQueryResult metricsQueryResult = metricsQueryClient.queryResource("{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());
        }
    }
}

Control de la respuesta de consulta de métricas

La API de consulta de métricas devuelve un MetricsQueryResult objeto . El MetricsQueryResult objeto contiene propiedades como una lista de MetricResultobjetos con tipo , granularitynamespace, y timeInterval. Se MetricResult puede tener acceso a la lista de objetos mediante el metrics parámetro . Cada MetricResult objeto de esta lista contiene una lista de TimeSeriesElement objetos . Cada TimeSeriesElement contiene data las propiedades y metadata_values . En forma visual, la jerarquía de objetos de la respuesta es similar a la estructura siguiente:

MetricsQueryResult
|---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

Obtención de métricas promedio y recuento

MetricsQueryClient metricsQueryClient = new MetricsQueryClientBuilder()
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildClient();

Response<MetricsQueryResult> metricsResponse = metricsQueryClient
    .queryResourceWithResponse("{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());
        }
    }
}

Solución de problemas

Consulte nuestra guía de solución de problemas para obtener más información sobre cómo diagnosticar varios escenarios de error.

Pasos siguientes

Para más información sobre Azure Monitor, consulte la documentación del servicio Azure Monitor.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

El proyecto ha adoptado el Código de conducta de código abierto de Microsoft. Para obtener más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones