Bibliothèque de client d’ingestion Azure Monitor pour Java - version 1.1.1

  • Article

La bibliothèque cliente d’ingestion Azure Monitor est utilisée pour envoyer des journaux personnalisés à Azure Monitor à l’aide de l’API Ingestion des journaux.

Cette bibliothèque vous permet d’envoyer des données à partir de pratiquement n’importe quelle source vers des tables intégrées prises en charge ou vers des tables personnalisées que vous créez dans l’espace de travail Log Analytics. Vous pouvez même étendre le schéma des tables intégrées avec des colonnes personnalisées.

Prise en main

Prérequis

Inclure le package

Inclure le fichier de nomenclature

Incluez le azure-sdk-bom à votre projet pour prendre une dépendance sur la dernière version stable 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-ingestion</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-ingestion</artifactId>
    <version>1.1.1</version>
</dependency>

Création du client

Un client authentifié est nécessaire pour charger les journaux dans Azure Monitor. 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. 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.10.1</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.

Client d’ingestion des journaux synchrones

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildClient();

Client d’ingestion des journaux asynchrones

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionAsyncClient asyncClient = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildAsyncClient();

Concepts clés

Point de terminaison de collecte de données

Les points de terminaison de collecte de données (DCE) vous permettent de configurer de manière unique les paramètres d’ingestion pour Azure Monitor. Cet article fournit une vue d’ensemble des points de terminaison de collecte de données, y compris leur contenu et leur structure, ainsi que la façon dont vous pouvez les créer et les utiliser.

Règle de collecte de données

Les règles de collecte de données (DCR) définissent les données collectées par Azure Monitor et spécifient comment et où ces données doivent être envoyées ou stockées. L’appel de l’API REST doit spécifier une règle de collecte de données à utiliser. Un seul point de terminaison de collecte de données peut prendre en charge plusieurs règles de collecte de données. Vous pouvez donc spécifier une règle de collecte de données différente pour chaque source et chaque table cible.

La règle de collecte de données doit comprendre la structure des données d’entrée et celle de la table cible. Si les deux ne correspondent pas, elle peut utiliser une transformation pour convertir les données sources en fonction de la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs et conversions.

Pour plus d’informations, consultez Règles de collecte de données dans Azure Monitor. Pour plus d’informations sur la récupération d’un ID DCR, consultez ce tutoriel.

Tables d’espace de travail Log Analytics

Les journaux personnalisés peuvent envoyer des données à n’importe quelle table personnalisée créée par vos soins et à certaines tables intégrées de votre espace de travail Log Analytics. La table cible doit déjà exister pour que vous puissiez lui envoyer des données. Les tables intégrées actuellement prises en charge sont les suivantes :

Récupération des journaux

Les journaux qui ont été chargés à l’aide de cette bibliothèque peuvent être interrogés à l’aide de la bibliothèque cliente de requête Azure Monitor .

Exemples

Charger des journaux personnalisés

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
client.upload("<data-collection-rule-id>", "<stream-name>", logs);
System.out.println("Logs uploaded successfully");

Charger des journaux personnalisés avec une concurrence maximale

Si la collection des journaux d’entrée est trop volumineuse, le client fractionne l’entrée en plusieurs demandes plus petites. Ces demandes sont envoyées en série, par défaut, mais en configurant la concurrence maximale dans LogsUploadOptions, ces demandes peuvent être envoyées simultanément au service, comme indiqué dans l’exemple ci-dessous.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setMaxConcurrency(3);
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);
System.out.println("Logs uploaded successfully");

Charger des journaux personnalisés avec gestion des erreurs

Lors du chargement d’une grande collection de journaux, le client fractionne l’entrée en plusieurs demandes de service plus petites. La méthode de chargement fournit une option permettant de gérer des erreurs de service individuelles par le biais d’un gestionnaire d’erreurs, comme illustré dans l’exemple ci-dessous. Ce gestionnaire d’erreurs inclut les détails de l’exception et la liste de tous les journaux qui n’ont pas pu être téléchargés. Si aucun gestionnaire d’erreurs n’est fourni, la méthode de chargement lève une exception d’agrégation qui inclut toutes les erreurs de service.

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();

LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setLogsUploadErrorConsumer(uploadLogsError -> {
            System.out.println("Error message " + uploadLogsError.getResponseException().getMessage());
            System.out.println("Total logs failed to upload = " + uploadLogsError.getFailedLogs().size());

            // throw the exception here to abort uploading remaining logs
            // throw uploadLogsError.getResponseException();
        });
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);

Dépannage

Pour plus d’informations sur le diagnostic de différents scénarios d’échec, consultez notre guide de résolution des problèmes.

Étapes suivantes

Vous trouverez d’autres exemples ici.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

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 les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.

Impressions