Azure Monitor-Erfassungsclientbibliothek für Java– Version 1.1.1

  • Artikel

Die Azure Monitor-Erfassungsclientbibliothek wird verwendet, um benutzerdefinierte Protokolle mithilfe der Protokollerfassungs-API an Azure Monitor zu senden.

Mit dieser Bibliothek können Sie Daten von praktisch jeder Quelle in unterstützte integrierte Tabellen oder an benutzerdefinierte Tabellen senden, die Sie im Log Analytics-Arbeitsbereich erstellen. Sie können sogar das Schema integrierter Tabellen mit benutzerdefinierten Spalten erweitern.

Erste Schritte

Voraussetzungen

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie die azure-sdk-bom in Ihr Projekt ein, um eine Abhängigkeit von der neuesten stabilen Version der Bibliothek zu nehmen. Ersetzen Sie im folgenden Codeausschnitt den Platzhalter {bom_version_to_target} durch die Versionsnummer. Weitere Informationen zur Stückliste finden Sie in der AZURE SDK-BOM-INFODATEI.

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

und fügen Sie dann die direkte Abhängigkeit in den Abschnitt abhängigkeiten ohne das Versionstag ein, wie unten gezeigt.

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

Direkte Abhängigkeiten einfügen

Wenn Sie abhängigkeiten von einer bestimmten Version der Bibliothek übernehmen möchten, die in der Stückliste nicht vorhanden ist, fügen Sie die direkte Abhängigkeit wie folgt zu Ihrem Projekt hinzu.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
    <version>1.1.1</version>
</dependency>

Erstellen des Clients

Zum Hochladen von Protokollen in Azure Monitor ist ein authentifizierter Client erforderlich. Die Bibliothek umfasst sowohl synchrone als auch asynchrone Formen der Clients. Für die Authentifizierung verwenden DefaultAzureCredentialBuilder die folgenden Beispiele das Paket azure-identity .

Authentifizieren über Azure Active Directory

Sie können sich mit Azure Active Directory mithilfe der Azure Identity-Bibliothek authentifizieren. Um den unten gezeigten Anbieter DefaultAzureCredential oder andere Anbieter von Anmeldeinformationen zu verwenden, die mit dem Azure SDK bereitgestellt werden, fügen Sie das azure-identity Paket ein:

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

Legen Sie die Werte der Client-ID, Mandanten-ID und geheimen Clientschlüssel der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Synchroner Protokollerfassungsclient

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

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

Client für die asynchrone Protokollerfassung

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

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

Wichtige Begriffe

Datensammlungsendpunkt

Mit Datensammlungsendpunkten (Data Collection Endpoints, DCEs) können Sie Erfassungseinstellungen für Azure Monitor eindeutig konfigurieren. Dieser Artikel bietet eine Übersicht über Datensammlungsendpunkte, einschließlich ihres Inhalts und ihrer Struktur und wie Sie sie erstellen und damit arbeiten können.

Datensammlungsregel

Datensammlungsregeln (Data Collection Rules, DCR) definieren Daten, die von Azure Monitor gesammelt werden, und geben an, wie und wo diese Daten gesendet oder gespeichert werden sollen. Der REST-API-Aufruf muss eine zu verwendende DCR angeben. Eine einzelne DCR kann mehrere DCRs unterstützen, weshalb Sie eine andere DCR für verschiedene Quellen und Zieltabellen angeben können.

Das DCR muss die Struktur der Eingabedaten und die Struktur der Zieltabelle erkennen. Wenn die beiden nicht übereinstimmen, kann eine Transformation durchgeführt werden, um die Quelldaten so zu konvertieren, dass sie mit der Zieltabelle kompatibel sind. Sie können die Transformation auch verwenden, um Quelldaten zu filtern und andere Berechnungen oder Konvertierungen durchzuführen.

Weitere Informationen finden Sie unter Datensammlungsregeln in Azure Monitor. Informationen zum Abrufen einer DCR-ID finden Sie in diesem Tutorial.

Log Analytics-Arbeitsbereichstabellen

Benutzerdefinierte Protokolle können Daten an jede von Ihnen erstellte benutzerdefinierte Tabelle und an bestimmte integrierte Tabellen in Ihrem Log Analytics-Arbeitsbereich senden. Die Zieltabelle muss existieren, bevor Sie Daten an sie senden können. Die folgenden integrierten Tabellen werden derzeit unterstützt:

Abrufen von Protokollen

Die Protokolle, die mit dieser Bibliothek hochgeladen wurden, können mithilfe der Azure Monitor Query-Clientbibliothek abgefragt werden.

Beispiele

Hochladen benutzerdefinierter Protokolle

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

Hochladen von benutzerdefinierten Protokollen mit maximaler Parallelität

Wenn die Sammlung in Eingabeprotokollen zu groß ist, teilt der Client die Eingabe in mehrere kleinere Anforderungen auf. Diese Anforderungen werden standardmäßig seriell gesendet, aber durch Konfigurieren der maximalen Parallelität in LogsUploadOptionskönnen diese Anforderungen gleichzeitig an den Dienst gesendet werden, wie im folgenden Beispiel gezeigt.

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

Hochladen benutzerdefinierter Protokolle mit Fehlerbehandlung

Beim Hochladen einer großen Sammlung von Protokollen teilt der Client die Eingabe in mehrere kleinere Dienstanforderungen auf. Die Uploadmethode bietet eine Option zum Behandeln einzelner Dienstfehler über einen Fehlerhandler, wie im folgenden Beispiel gezeigt. Dieser Fehlerhandler enthält die Ausnahmedetails und die Liste aller Protokolle, die nicht hochgeladen werden konnten. Wenn kein Fehlerhandler bereitgestellt wird, löst die Uploadmethode eine aggregierte Ausnahme aus, die alle Dienstfehler enthält.

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

Problembehandlung

Ausführliche Informationen zur Diagnose verschiedener Fehlerszenarien finden Sie in unserem Leitfaden zur Problembehandlung.

Nächste Schritte

Weitere Beispiele finden Sie hier.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. 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. Ausführliche Informationen finden Sie unter https://cla.microsoft.com.

Wenn Sie einen Pull Request (PR) übermitteln, überprüft ein CLA-Bot automatisch, ob Sie eine Lizenzvereinbarung bereitstellen und den PR entsprechend ergänzen müssen (z.B. mit einer Bezeichnung oder einem Kommentar). Führen Sie einfach die Anweisungen des Bots aus. Sie müssen dies nur einmal für alle Repositorys ausführen, die unsere CLA verwenden.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Aufrufe