Biblioteca de clientes de Consulta do Azure Monitor para Java – versão 1.2.6

A biblioteca de clientes de Consulta do Azure Monitor é usada para executar consultas somente leitura nas duas plataformas de dados do Azure Monitor:

• Logs – coleta e organiza dados de log e desempenho de recursos monitorados. Dados de diferentes fontes, como logs de plataforma de serviços do Azure, dados de log e desempenho de agentes de máquinas virtuais, e dados de uso e desempenho de aplicativos podem ser consolidados em um único workspace do Azure Log Analytics. Os vários tipos de dados podem ser analisados juntos usando o Linguagem de Consulta Kusto.
• Métricas – coleta dados numéricos de recursos monitorados em um banco de dados de série temporal. Métricas são valores numéricos que são coletados a intervalos regulares e descrevem algum aspecto de um sistema em um determinado momento. As métricas são leves e capazes de dar suporte a cenários quase em tempo real, tornando-as particularmente úteis para alertas e detecção rápida de problemas.

Recursos:

• Código-fonte
• Pacote (Maven)
• Documentação de referência da API
• Documentação do serviço
• Amostras
• Log de alterações

Introdução

Pré-requisitos

• Um Java Development Kit (JDK) versão 8 ou posterior
• Uma assinatura do Azure
• Uma implementação de TokenCredential, como um tipo de credencial de biblioteca de identidade do Azure.
• Para consultar logs, você precisa de um workspace do Azure Log Analytics ou um recurso do Azure de qualquer tipo (Conta de Armazenamento, Key Vault, Cosmos DB etc.).
• Para consultar Métricas, você precisa de um recurso do Azure de qualquer tipo (Conta de Armazenamento, Key Vault, Cosmos DB etc.).

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do 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>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

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

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

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

Crie o cliente

Um cliente autenticado é necessário para consultar Logs ou Métricas. A biblioteca inclui formas síncronas e assíncronas dos clientes. Para autenticar, os exemplos a seguir usam DefaultAzureCredentialBuilder do pacote azure-identity .

Autenticando usando o Azure Active Directory

Você pode autenticar com o Azure Active Directory usando a biblioteca de identidade do Azure. Observe que os pontos de extremidade regionais não dão suporte à autenticação do AAD. Crie um subdomínio personalizado para o recurso para usar esse tipo de autenticação.

Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, inclua o azure-identity pacote:

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

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET.

Clientes síncronos

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

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

Clientes assíncronos

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

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

Configurar clientes para nuvens não públicas do Azure

Por padrão, LogQueryClient e MetricQueryClient são configurados para se conectar à nuvem pública do Azure. Eles podem ser configurados para se conectar a nuvens não públicas do Azure definindo o correto endpoint nos construtores de cliente: Por exemplo:

Criando um para a LogsQueryClient nuvem do Azure China:

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

Criando um para a MetricsQueryClient nuvem do Azure China:

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

Executar a consulta

Para obter exemplos de consultas de Logs e Métricas, consulte a seção Exemplos .

Principais conceitos

Limites e limitação da taxa de consulta de logs

O serviço Log Analytics aplica limitação quando a taxa de solicitação é muito alta. Limites, como o número máximo de linhas retornadas, também são aplicados às consultas Kusto. Para obter mais informações, consulte API de Consulta.

Estrutura de dados de métricas

Cada conjunto de valores de métrica é uma série temporal com as seguintes características:

• A hora em que o valor foi coletado
• O recurso associado ao valor
• Um namespace que funciona como uma categoria para a métrica
• Um nome de métrica
• O valor em si
• Algumas métricas podem ter várias dimensões, conforme descrito em métricas multidimensionais. As métricas personalizadas podem ter até 10 dimensões.

Exemplos

• Consulta de logs
  • Mapear os resultados da consulta de logs para um modelo
  • Manipular a resposta da consulta de logs
  • Consultar logs por ID do recurso
  • Criar um cliente de log para nuvens não públicas do Azure
• Consulta de logs do Lote
• Cenários de consulta de logs avançados
  • Definir tempo limite de consulta de logs
  • Consultar vários espaços de trabalho
  • Incluir estatísticas
  • Incluir visualização
• Consulta de métricas
  • Manipular a resposta da consulta de métricas
  • Obter métricas de média e contagem
  • Criar um cliente de métricas para nuvens não públicas do Azure

Consulta de logs

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"));
}

Mapear os resultados da consulta de logs para um 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());
}

Manipular a resposta da consulta de logs

A query API retorna o LogsQueryResult, enquanto a queryBatch API retorna o LogsBatchQueryResult. Aqui está uma hierarquia da resposta:

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

Consultar logs por ID do recurso

O LogsQueryClient dá suporte à consulta de logs usando uma ID do workspace (queryWorkspace métodos) ou uma ID de recurso (queryResource métodos). Um exemplo de consulta de logs usando uma ID de recurso é mostrado abaixo. Alterações semelhantes podem ser aplicadas a todos os outros exemplos.

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 logs do Lote

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());
}

Cenários de consulta de logs avançados

Definir tempo limite de consulta de logs

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);

Consultar vários espaços de trabalho

Para executar a mesma consulta em vários workspaces do Log Analytics, use o LogsQueryOptions.setAdditionalWorkspaces método :

Quando vários workspaces são incluídos na consulta, os logs na tabela de resultados não são agrupados de acordo com o workspace do qual ele foi recuperado. Para identificar o workspace de uma linha na tabela de resultados, você pode inspecionar a coluna "TenantId" na tabela de resultados. Se essa coluna não estiver na tabela, talvez seja necessário atualizar a cadeia de caracteres de consulta para incluir essa coluna.

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 estatísticas

Para obter estatísticas de execução de consulta de logs, como consumo de CPU e memória:

1. Use LogsQueryOptions para solicitar estatísticas na resposta definindo setIncludeStatistics() como true.
2. Invoque o getStatistics método no LogsQueryResult objeto .

O exemplo a seguir imprime o tempo de execução da 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());

Como a estrutura do conteúdo de estatísticas varia de acordo com a consulta, um BinaryData tipo de retorno é usado. Ele contém a resposta JSON bruta. As estatísticas são encontradas na query propriedade do JSON. Por exemplo:

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

Incluir visualização

Para obter dados de visualização para consultas de logs usando o operador de renderização:

1. Use LogsQueryOptions para solicitar dados de visualização na resposta definindo setIncludeVisualization() como true.
2. Invoque o getVisualization método no LogsQueryResult objeto .

Por exemplo:

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());

Como a estrutura da carga de visualização varia de acordo com a consulta, um BinaryData tipo de retorno é usado. Ele contém a resposta JSON bruta. Por exemplo:

{
  "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

Uma ID de recurso, conforme indicado pelo {resource-id} espaço reservado no exemplo abaixo, é necessária para consultar métricas. Para localizar a ID do recurso:

1. Navegue até a página do recurso no portal do Azure.
2. Na folha Visão geral , selecione o link Modo de Exibição JSON .
3. No JSON resultante, copie o valor da id propriedade .

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());
        }
    }
}

Manipular resposta de consulta de métricas

A API de consulta de métricas retorna um MetricsQueryResult objeto . O MetricsQueryResult objeto contém propriedades como uma lista de MetricResultobjetos do tipo , granularity, namespacee timeInterval. A MetricResult lista de objetos pode ser acessada usando o metrics parâmetro . Cada MetricResult objeto nesta lista contém uma lista de TimeSeriesElement objetos. Cada TimeSeriesElement um contém data propriedades e metadata_values . No formato visual, a hierarquia de objeto da resposta se assemelha à seguinte estrutura:

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

Obter métricas médias e de contagem

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());
        }
    }
}

Solução de problemas

Consulte nosso guia de solução de problemas para obter detalhes sobre como diagnosticar vários cenários de falha.

Próximas etapas

Para saber mais sobre o Azure Monitor, confira a documentação do serviço do Azure Monitor.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder e de fato concede, os direitos de usar sua contribuição.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o código de conduta ou entre em contato com opencode@microsoft.com para enviar outras perguntas ou comentários.