Bibliothèque cliente de requête Azure Monitor pour Java - version 1.2.6

Article
10/21/2023

La bibliothèque cliente de requête Azure Monitor est utilisée pour exécuter des requêtes en lecture seule sur les deux plateformes de données d’Azure Monitor :

Journaux : collecte et organise les données de journal et de performances à partir des ressources supervisées. Les données provenant de différentes sources telles que les journaux de plateforme des services Azure, les données de journal et de performances des agents de machines virtuelles, ainsi que les données d’utilisation et de performances des applications peuvent être consolidées dans un seul espace de travail Azure Log Analytics. Les différents types de données peuvent être analysés ensemble à l’aide de la Langage de requête Kusto.
Métriques : collecte des données numériques à partir des ressources surveillées dans une base de données de séries chronologiques. Les métriques sont des valeurs numériques collectées à intervalles réguliers et qui décrivent un certain aspect d’un système à un moment donné. Les métriques sont légères et capables de prendre en charge des scénarios en quasi-temps réel, ce qui les rend particulièrement utiles pour les alertes et la détection rapide des problèmes.

Ressources :

Prise en main

Prérequis

Un Kit de développement Java (JDK), version 8 ou ultérieure
Un abonnement Azure
Une implémentation TokenCredential, par exemple un type d’informations d'identification de la bibliothèque d’identités Azure.
Pour interroger les journaux, vous avez besoin d’un espace de travail Azure Log Analytics ou d’une ressource Azure de tout type (compte de stockage, Key Vault, Cosmos DB, etc.).
Pour interroger des métriques, vous avez besoin d’une ressource Azure de tout type (compte de stockage, Key Vault, Cosmos DB, etc.).

Inclure le package

Inclure le fichier de nomenclature

Incluez azure-sdk-bom dans votre projet pour dépendre de la version de disponibilité générale de la bibliothèque. Dans l’extrait de code suivant, remplacez l’espace réservé {bom_version_to_target} par le numéro de version. Pour en savoir plus sur la nomenclature, consultez le README BOM du KIT DE DÉVELOPPEMENT LOGICIEL 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>

puis incluez la dépendance directe dans la section dépendances sans la balise de version, comme indiqué ci-dessous.

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

Inclure une dépendance directe

Si vous souhaitez dépendre d’une version particulière de la bibliothèque qui n’est pas présente dans la nomenclature, ajoutez la dépendance directe à votre projet comme suit.

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

Création du client

Un client authentifié est nécessaire pour interroger les journaux ou les métriques. La bibliothèque inclut des formes synchrones et asynchrones des clients. Pour l’authentification, les exemples suivants utilisent DefaultAzureCredentialBuilder à partir du package azure-identity .

Authentification à l’aide d’Azure Active Directory

Vous pouvez vous authentifier auprès d’Azure Active Directory à l’aide de la bibliothèque Azure Identity. Notez que les points de terminaison régionaux ne prennent pas en charge l’authentification AAD. Créez un sous-domaine personnalisé pour votre ressource afin d’utiliser ce type d’authentification.

Pour utiliser le fournisseur DefaultAzureCredential indiqué ci-dessous ou d’autres fournisseurs d’informations d’identification fournis avec le Kit de développement logiciel (SDK) Azure, incluez le azure-identity package :

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

Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET.

Clients synchrones

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

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

Clients asynchrones

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

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

Configurer des clients pour des clouds Azure non publics

Par défaut, LogQueryClient et MetricQueryClient sont configurés pour se connecter au cloud Azure public. Ceux-ci peuvent être configurés pour se connecter à des clouds Azure non publics en définissant la valeur correcte endpoint dans les générateurs de clients : Par exemple :

Création d’un LogsQueryClient pour le cloud Azure Chine :

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

Création d’un MetricsQueryClient pour le cloud Azure Chine :

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

exécuter la requête.

Pour obtenir des exemples de requêtes de journaux et de métriques, consultez la section Exemples .

Concepts clés

Limites et limitation du taux de requête des journaux

Le service Log Analytics applique une limitation lorsque le taux de requêtes est trop élevé. Des limites, telles que le nombre maximal de lignes retournées, sont également appliquées aux requêtes Kusto. Pour plus d’informations, consultez API de requête.

Structure des données des métriques

Chaque ensemble de valeurs de métriques est une série chronologique avec les caractéristiques suivantes :

L’heure à laquelle la valeur a été collectée
Ressource associée à la valeur
Un espace de noms qui agit comme une catégorie pour la métrique
Un nom de métrique
La valeur elle-même
Certaines métriques peuvent avoir plusieurs dimensions, comme décrit dans Métriques multidimensionnelles. Les métriques personnalisées peuvent avoir jusqu’à 10 dimensions.

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

Mapper les résultats de la requête des journaux à un modèle

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

Gérer la réponse aux requêtes des journaux

L’API query retourne le LogsQueryResult, tandis que l’API queryBatch retourne le LogsBatchQueryResult. Voici une hiérarchie de la réponse :

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

Journaux de requête par ID de ressource

Prend en charge l’interrogation LogsQueryClient des journaux à l’aide d’un ID d’espace de travail (queryWorkspace méthodes) ou d’un ID de ressource (queryResource méthodes). Vous trouverez ci-dessous un exemple d’interrogation des journaux à l’aide d’un ID de ressource. Des modifications similaires peuvent être appliquées à tous les autres exemples.

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

Requête des journaux Batch

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

Scénarios de requête de journaux avancés

Définir le délai d’expiration de requête des journaux

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

Interroger plusieurs espaces de travail

Pour exécuter la même requête sur plusieurs espaces de travail Log Analytics, utilisez la LogsQueryOptions.setAdditionalWorkspaces méthode :

Lorsque plusieurs espaces de travail sont inclus dans la requête, les journaux dans la table de résultats ne sont pas regroupés en fonction de l’espace de travail à partir duquel ils ont été récupérés. Pour identifier l’espace de travail d’une ligne dans la table de résultats, vous pouvez inspecter la colonne « TenantId » dans la table de résultats. Si cette colonne ne figure pas dans la table, vous devrez peut-être mettre à jour votre chaîne de requête pour inclure cette colonne.

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

Inclure des statistiques

Pour obtenir les statistiques d’exécution des requêtes des journaux, telles que la consommation de processeur et de mémoire :

Utilisez LogsQueryOptions pour demander des statistiques dans la réponse en définissant sur truesetIncludeStatistics() .
Appelez la getStatistics méthode sur l’objet LogsQueryResult .

L’exemple suivant imprime l’heure d’exécution de la requête :

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

Étant donné que la structure de la charge utile des statistiques varie selon la requête, un BinaryData type de retour est utilisé. Il contient la réponse JSON brute. Les statistiques se trouvent dans la query propriété du JSON. Par exemple :

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

Inclure la visualisation

Pour obtenir des données de visualisation pour les requêtes de journaux à l’aide de l’opérateur de rendu :

Utilisez LogsQueryOptions pour demander des données de visualisation dans la réponse en définissant sur setIncludeVisualization()true.
Appelez la getVisualization méthode sur l’objet LogsQueryResult .

Par exemple :

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

Étant donné que la structure de la charge utile de visualisation varie selon la requête, un BinaryData type de retour est utilisé. Il contient la réponse JSON brute. Par exemple :

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

Requête de métriques

Un ID de ressource, comme indiqué par l’espace réservé dans l’exemple {resource-id} ci-dessous, est requis pour interroger les métriques. Pour rechercher l’ID de ressource :

Accédez à la page de votre ressource dans le Portail Azure.
Dans le panneau Vue d’ensemble , sélectionnez le lien Affichage JSON .
Dans le json résultant, copiez la valeur de la id propriété .

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

Gérer la réponse de requête des métriques

L’API de requête de métriques retourne un MetricsQueryResult objet. L’objet MetricsQueryResult contient des propriétés telles qu’une liste d’objets MetricResult-typed, granularity, namespaceet timeInterval. La MetricResult liste d’objets est accessible à l’aide du metrics param. Chaque MetricResult objet de cette liste contient une liste d’objets TimeSeriesElement . Chaque TimeSeriesElement contient des data propriétés et metadata_values . Sous forme visuelle, la hiérarchie d’objets de la réponse ressemble à la structure suivante :

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

Obtenir la moyenne et compter les métriques

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

Dépannage

Consultez notre guide de résolution des problèmes pour plus d’informations sur la façon de diagnostiquer différents scénarios d’échec.

Étapes suivantes

Pour en savoir plus sur Azure Monitor, consultez la documentation du service Azure Monitor.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) spécifiant que vous avez le droit de nous accorder les droits d’utiliser votre contribution, et que vous nous les accordez.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d'informations, consultez la FAQ du Code de conduite ou contactez opencode@microsoft.com pour toute question ou commentaire supplémentaire.

Impressions