Azure Monitor Query-Clientbibliothek für Java – Version 1.2.6

Die Azure Monitor Query-Clientbibliothek wird verwendet, um schreibgeschützte Abfragen für die beiden Datenplattformen von Azure Monitor auszuführen:

• Protokolle : Erfasst und organisiert Protokoll- und Leistungsdaten aus überwachten Ressourcen. Daten aus verschiedenen Quellen wie Plattformprotokolle von Azure-Diensten, Protokoll- und Leistungsdaten von Agents für virtuelle Computer sowie Nutzungs- und Leistungsdaten aus Apps können in einem einzelnen Azure Log Analytics-Arbeitsbereich konsolidiert werden. Die verschiedenen Datentypen können mithilfe des Kusto-Abfragesprache zusammen analysiert werden.
• Metriken : Erfasst numerische Daten aus überwachten Ressourcen in einer Zeitreihendatenbank. Metriken sind numerische Werte, die in regelmäßigen Abständen erfasst werden und einen Aspekt eines Systems zu einem bestimmten Zeitpunkt beschreiben. Metriken sind einfach und in der Lage, Szenarien nahezu in Echtzeit zu unterstützen, was sie besonders nützlich für Warnungen und schnelle Erkennung von Problemen macht.

Ressourcen:

• Quellcode
• Maven-Paket
• API-Referenzdokumentation
• Dienstdokumentation
• Beispiele
• Änderungsprotokoll

Erste Schritte

Voraussetzungen

• Java Development Kit (JDK), Version 8 oder höher
• Ein Azure-Abonnement
• Eine TokenCredential-Implementierung, z. B. ein Anmeldeinformationstyp der Azure Identity-Bibliothek.
• Zum Abfragen von Protokollen benötigen Sie einen Azure Log Analytics-Arbeitsbereich oder eine Azure-Ressource jeglicher Art (Speicherkonto, Key Vault, Cosmos DB usw.).
• Zum Abfragen von Metriken benötigen Sie eine Azure-Ressource jeglicher Art (Speicherkonto, Key Vault, Cosmos DB usw.).

Einschließen des Pakets

BOM-Datei einfügen

Fügen Sie das azure-sdk-bom in Ihr Projekt ein, um die Abhängigkeit von der General Availability (GA)-Version der Bibliothek zu übernehmen. 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-query</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-query</artifactId>
    <version>1.2.6</version>
</dependency>

Erstellen des Clients

Zum Abfragen von Protokollen oder Metriken 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. Beachten Sie, dass regionale Endpunkte die AAD-Authentifizierung nicht unterstützen. Erstellen Sie eine benutzerdefinierte Unterdomäne für Ihre Ressource, um diesen Authentifizierungstyp zu verwenden.

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.9.0</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.

Synchrone Clients

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

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

Asynchrone Clients

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

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

Konfigurieren von Clients für nicht öffentliche Azure-Clouds

Standardmäßig sind und MetricQueryClient so konfiguriert, LogQueryClient dass eine Verbindung mit der öffentlichen Azure Cloud hergestellt wird. Diese können so konfiguriert werden, dass eine Verbindung mit nicht öffentlichen Azure-Clouds hergestellt wird, indem Sie die richtige endpoint in den Client-Generatoren festlegen: Beispiel:

Erstellen einer LogsQueryClient Cloud für Azure China:

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

Erstellen einer MetricsQueryClient Cloud für Azure China:

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

Führen Sie die Abfrage aus.

Beispiele für Protokolle und Metrikabfragen finden Sie im Abschnitt Beispiele .

Wichtige Begriffe

Protokollabfrageratenlimits und Drosselung

Der Log Analytics-Dienst wendet eine Drosselung an, wenn die Anforderungsrate zu hoch ist. Grenzwerte, z. B. die maximale Anzahl zurückgegebener Zeilen, werden auch auf die Kusto-Abfragen angewendet. Weitere Informationen finden Sie unter Abfrage-API.

Metrikdatenstruktur

Jeder Satz von Metrikwerten ist eine Zeitreihe mit den folgenden Merkmalen:

• Zeitpunkt, zu dem der Wert erfasst wurde
• Die dem Wert zugeordnete Ressource
• Namespace, der wie eine Kategorie für die Metrik fungiert
• Metrikname
• Eigentlicher Wert
• Einige Metriken können mehrere Dimensionen aufweisen, wie in mehrdimensionalen Metriken beschrieben. Benutzerdefinierte Metriken können über bis zu 10 Dimensionen verfügen.

Beispiele

• Protokollabfrage
  • Zuordnen von Protokollabfrageergebnissen zu einem Modell
  • Behandeln von Protokollabfrageantworten
  • Abfragen von Protokollen nach Ressourcen-ID
  • Erstellen eines Protokollclients für nicht öffentliche Azure-Clouds
• Batchprotokollabfrage
• Szenarien mit erweiterten Protokollabfragen
  • Festlegen des Abfragetimeouts für Protokolle
  • Abfragen mehrerer Arbeitsbereiche
  • Statistiken einschließen
  • Visualisierung einschließen
• Metrikabfrage
  • Verarbeiten von Metrikabfrageantworten
  • Abrufen von Metriken für Durchschnitt und Anzahl
  • Erstellen eines Metrikclients für nicht öffentliche Azure-Clouds

Protokollabfrage

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

Zuordnen von Protokollabfrageergebnissen zu einem Modell

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

Behandeln von Protokollabfrageantworten

Die query API gibt den LogsQueryResultzurück, während die queryBatch API den LogsBatchQueryResultzurückgibt. Hier sehen Sie eine Hierarchie der Antwort:

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

Abfragen von Protokollen nach Ressourcen-ID

Die LogsQueryClient unterstützt das Abfragen von Protokollen mithilfe einer Arbeitsbereichs-ID (queryWorkspace Methoden) oder einer Ressourcen-ID (queryResource Methoden). Ein Beispiel für das Abfragen von Protokollen mithilfe einer Ressourcen-ID ist unten dargestellt. Ähnliche Änderungen können auf alle anderen Beispiele angewendet werden.

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

Batchprotokollabfrage

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

Szenarien mit erweiterten Protokollabfragen

Festlegen des Abfragetimeouts für Protokolle

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

Abfragen mehrerer Arbeitsbereiche

Verwenden Sie LogsQueryOptions.setAdditionalWorkspaces die -Methode, um dieselbe Abfrage für mehrere Log Analytics-Arbeitsbereiche auszuführen:

Wenn mehrere Arbeitsbereiche in der Abfrage enthalten sind, werden die Protokolle in der Ergebnistabelle nicht nach dem Arbeitsbereich gruppiert, aus dem sie abgerufen wurden. Um den Arbeitsbereich einer Zeile in der Ergebnistabelle zu identifizieren, können Sie die Spalte "TenantId" in der Ergebnistabelle überprüfen. Wenn diese Spalte nicht in der Tabelle enthalten ist, müssen Sie möglicherweise Ihre Abfragezeichenfolge aktualisieren, um diese Spalte einzuschließen.

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

Statistiken einschließen

So rufen Sie Protokollabfrageausführungsstatistiken ab, z. B. CPU- und Arbeitsspeicherverbrauch:

1. Verwenden SieLogsQueryOptions, um Statistiken in der Antwort anzufordern, indem Sie auf truefestlegensetIncludeStatistics().
2. Rufen Sie die getStatistics -Methode für das LogsQueryResult -Objekt auf.

Im folgenden Beispiel wird die Abfrageausführungszeit ausgegeben:

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

Da die Struktur der Statistiknutzlast je nach Abfrage variiert, wird ein BinaryData Rückgabetyp verwendet. Sie enthält die unformatierte JSON-Antwort. Die Statistiken befinden sich in der query Eigenschaft des JSON-Objekts. Beispiel:

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

Visualisierung einschließen

So rufen Sie Visualisierungsdaten für Protokollabfragen mithilfe des Renderoperators ab:

1. Verwenden SieLogsQueryOptions, um Visualisierungsdaten in der Antwort anzufordern, indem Sie auf truefestlegensetIncludeVisualization().
2. Rufen Sie die getVisualization -Methode für das LogsQueryResult -Objekt auf.

Beispiel:

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

Da die Struktur der Visualisierungsnutzlast je nach Abfrage variiert, wird ein BinaryData Rückgabetyp verwendet. Sie enthält die unformatierte JSON-Antwort. Beispiel:

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

Metrikabfrage

Zum Abfragen von {resource-id} Metriken ist eine Ressourcen-ID erforderlich, wie sie im folgenden Beispiel durch den Platzhalter angegeben wird. So suchen Sie die Ressourcen-ID:

1. Navigieren Sie im Azure-Portal zur Seite Ihrer Ressource.
2. Wählen Sie auf dem Blatt Übersicht den Link JSON-Ansicht aus.
3. Kopieren Sie im resultierenden JSON-Code den Wert der id -Eigenschaft.

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

Verarbeiten von Metrikabfrageantworten

Die Metrikabfrage-API gibt ein MetricsQueryResult Objekt zurück. Das MetricsQueryResult -Objekt enthält Eigenschaften wie eine Liste von MetricResult-typisierten Objekten, granularity, namespaceund timeInterval. Auf die MetricResult Objektliste kann über den metrics Param zugegriffen werden. Jedes MetricResult Objekt in dieser Liste enthält eine Liste von TimeSeriesElement Objekten. Jede TimeSeriesElement enthält data und metadata_values Eigenschaften. In visueller Form ähnelt die Objekthierarchie der Antwort der folgenden Struktur:

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

Abrufen von Metriken für Durchschnitt und Anzahl

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

Problembehandlung

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

Nächste Schritte

Weitere Informationen zu Azure Monitor finden Sie in der Dokumentation zum Azure Monitor-Dienst.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Für die meisten Beiträge ist die Zustimmung zu einer Lizenzvereinbarung für Mitwirkende (Contributor License Agreement, CLA) erforderlich, in der Sie erklären, dass Sie dazu berechtigt sind, uns die Rechte für die Nutzung Ihres Beitrags zu erteilen, und dies auch tun.

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 Kommentare haben.