Azure Metrics Advisor-Clientbibliothek für Java – Version 1.1.19

Artikel
10/21/2023

Azure Metrics Advisor ist ein neuer Cognitive Service, der zeitreihenbasierte Entscheidungs-KI verwendet, um die Problembehandlung bei Vorfällen von Onlinedienste zu identifizieren und zu unterstützen und die Geschäftsintegrität zu überwachen, indem der Slice und die Würfel von GeschäftsdatenFeedMetrics automatisiert werden.

Quellcode | Paket (Maven) | API-Referenzdokumentation | Produktdokumentation | Proben

Erste Schritte

Voraussetzungen

Java Development Kit (JDK) Version 8 oder höher
Azure-Abonnement
Cognitive Services- oder Metrics Advisor-Konto , um dieses Paket zu verwenden.

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-ai-metricsadvisor</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. Hinweis: Diese Version zielt auf die Azure Metrics Advisor-Dienst-API Version 1.0 ab.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-metricsadvisor</artifactId>
    <version>1.1.19</version>
</dependency>

Erstellen einer Metrics Advisor-Ressource

Authentifizieren des Clients

Um mit dem Metrics Advisor-Dienst zu interagieren, müssen Sie eine instance des Metrics Advisor-Clients erstellen. Sowohl die asynchronen als auch die synchronen Clients können mithilfe MetricsAdvisorClientBuildervon erstellt werden. Beim Aufrufen buildClient() wird der synchrone Client erstellt, während beim Aufrufen buildAsyncClient dessen asynchrones Pendant erstellt wird.

Nachschlagen des Endpunkts

Sie finden den Endpunkt für Ihre Metric Advisor-Ressource im Azure-Portal oder in der Azure CLI.

# Get the endpoint for the resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Erstellen eines MetricsAdvisor-Clients mithilfe von MetricsAdvisorKeyCredential

Sie benötigen zwei Schlüssel, um den Client zu authentifizieren:

Der Abonnementschlüssel für Ihre Metrics Advisor-Ressource. Sie finden ihn im Azure-Portal im Abschnitt Schlüssel und Endpunkt für Ihre Ressource.
Der API-Schlüssel für Ihre Metrics Advisor-Instanz. Sie finden dies im Webportal für Metrics Advisor unter API-Schlüssel im linken Navigationsmenü.

Sobald Sie über die beiden Schlüssel und den Endpunkt verfügen, können Sie die MetricsAdvisorKeyCredential -Klasse verwenden, um die Clients wie folgt zu authentifizieren:

Erstellen eines Metrics Advisor-Clients mit „MetricsAdvisorKeyCredential“

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorClient metricsAdvisorClient = new MetricsAdvisorClientBuilder()
    .endpoint("{endpoint}")
    .credential(credential)
    .buildClient();

Erstellen eines Clients für die Metrikverwaltung mit „MetricsAdvisorKeyCredential“

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorAdministrationClient metricsAdvisorAdminClient =
    new MetricsAdvisorAdministrationClientBuilder()
        .endpoint("{endpoint}")
        .credential(credential)
        .buildClient();

Erstellen eines MetricsAdvisor-Clients mithilfe von Azure Service Directory

Das Azure SDK für Java unterstützt ein Azure Identity-Paket, das das Abrufen von Anmeldeinformationen von Microsoft Identity Platform vereinfacht.

Die Authentifizierung mit AAD erfordert eine anfängliche Einrichtung:

Hinzufügen des Azure Identity-Pakets

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

Registrieren einer neuen Azure Active Directory-Anwendung
Gewähren Sie zugriff auf Metrics Advisor, indem Sie die "Cognitive Services User" Rolle Ihrem Dienstprinzipal zuweisen.

Nach dem Setup können Sie auswählen, welcher Typ von Anmeldeinformationen aus azure.identity verwendet werden soll. Als Beispiel kann DefaultAzureCredential verwendet werden, um den Client zu authentifizieren: Legen Sie die Werte der Client-ID, der Mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

Die Autorisierung ist am einfachsten mit DefaultAzureCredential. Es findet die besten Anmeldeinformationen, die in seiner ausgeführten Umgebung verwendet werden können. Weitere Informationen zur Verwendung der Azure Active Directory-Autorisierung mit Metrics Advisor finden Sie in der zugehörigen Dokumentation.

Erstellen eines Metrics Advisor-Clients mithilfe der AAD-Authentifizierung

TokenCredential credential = new DefaultAzureCredentialBuilder().build();
MetricsAdvisorClient metricsAdvisorClient = new MetricsAdvisorClientBuilder()
    .endpoint("{endpoint}")
    .credential(credential)
    .buildClient();

Erstellen eines Metrikverwaltungsclients mithilfe der AAD-Authentifizierung

TokenCredential credential = new DefaultAzureCredentialBuilder().build();
MetricsAdvisorAdministrationClient metricsAdvisorAdminClient =
    new MetricsAdvisorAdministrationClientBuilder()
        .endpoint("{endpoint}")
        .credential(credential)
        .buildClient();

Wichtige Begriffe

MetricsAdvisorClient

MetricsAdvisorClient hilft bei:

Diagnose von Anomalien und Vorfällen und Hilfe bei der Ursachenanalyse von Vorfällen.
Rufen Sie ursprüngliche Zeitreihendaten und Zeitreihendaten ab, die durch den Dienst angereichert wurden.
Senden sie Echtzeitwarnungen über mehrere Benachrichtigungshaken.
Passen Sie die Anomalie-/Incidenterkennung mithilfe von Feedback an, um Ihr Modell zu optimieren.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient ermöglicht Ihnen,

Verwalten von Datenfeeds
Auflisten verfügbarer Metriken und ihrer Erkennungskonfigurationen
Optimieren von Anomalieerkennungskonfigurationen
Konfigurieren von Konfigurationen für Anomaliewarnungen
Verwalten von Benachrichtigungshaken

Datenfeed

Ein Datenfeed erfasst Metrics Advisor aus der benutzerdefinierten Datenquelle, z. B. Cosmos-Strukturdatenstrom, SQL-Abfrageergebnis usw. Sie enthält Zeilen mit Zeitstempeln, null oder mehr Dimensionen, mindestens eine Metrik. Daher können mehrere Metriken dieselbe Datenquelle und sogar denselben Datenfeed gemeinsam nutzen.

Datenfeedmetrik

Eine Metrik ist ein quantifizierbares Measure, das verwendet wird, um die status eines bestimmten Geschäftsprozesses nachzuverfolgen und zu bewerten. Dies kann eine Kombination aus mehreren Zeitreihenwerten sein, die durch Dimensionen unterteilt sind, z. B. die Benutzeranzahl für eine vertikale Web- und en-us-Markt.

Datenfeeddimension

Eine Dimension ist mindestens ein kategorischer Wert des bereitgestellten Datenfeeds. Mit der Kombination dieser Werte wird eine bestimmte univariate Zeitreihe identifiziert, z. B. Land, Sprache, Mandant usw.

Metrikreihen

Metrikreihen sind eine Reihe von Datenpunkten, die in der Zeitreihenfolge indiziert (oder aufgelistet oder graphiert) sind. In der Regel ist eine Zeitreihe eine Sequenz, die zu aufeinanderfolgenden, gleichmäßig verteilten Zeitpunkten genommen wird. Daher handelt es sich um eine Sequenz diskreter Zeitdaten.

Konfiguration der Anomalieerkennung

Eine Konfiguration zur Anomalieerkennung ist eine Konfiguration, die für eine Zeitreihe bereitgestellt wird, um zu identifizieren, ob der Datenpunkt als Anomalie erkannt wird. Eine Metrik kann eine oder mehrere Erkennungskonfigurationen anwenden. Während eine Standarderkennungskonfiguration automatisch auf jede Metrik (mit dem Namen "Standard") angewendet wird, können wir die für unsere Daten verwendeten Erkennungsmodi optimieren, indem wir eine benutzerdefinierte Anomalieerkennungskonfiguration erstellen.

Anomalievorfall

Incidents werden für Reihen generiert, wenn sie abhängig von den angewendeten Anomalieerkennungskonfigurationen eine Anomalie aufweisen. Der Metrics Advisor-Dienst gruppiert eine Reihe von Anomalien innerhalb einer Metrik zu einem Incident.

Anomaliewarnung

Anomaliewarnungen können so konfiguriert werden, dass sie ausgelöst werden, wenn bestimmte Anomalien erfüllt werden. Sie können mehrere Warnungen mit unterschiedlichen Einstellungen festlegen. Sie können beispielsweise eine AnomalieAlert für Anomalien mit geringeren geschäftlichen Auswirkungen und eine andere für wichtigere Warnungen erstellen.

Notification Hook

Ein Benachrichtigungshaken ist der Einstiegspunkt, mit dem Benutzer Echtzeitwarnungen abonnieren können. Diese Warnungen werden mithilfe eines Hooks über das Internet gesendet.

Beispiele

Hinzufügen eines Datenfeeds aus einer Beispiel- oder Datenquelle
Check ingestion status
Konfigurieren der Konfiguration der Anomalieerkennung
Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen
Konfigurieren einer Anomaliewarnungskonfiguration
Abfragen von Anomalieerkennungsergebnissen

Hinzufügen eines Datenfeeds aus einem Beispiel oder aus einer Datenquelle

In diesem Beispiel werden die vom Benutzer angegebenen SQLServerDataFeedSource Datenfeedquelldaten für den Dienst erfasst.

DataFeed dataFeed = new DataFeed()
    .setName("dataFeedName")
    .setSource(new MySqlDataFeedSource("conn-string", "query"))
    .setGranularity(new DataFeedGranularity().setGranularityType(DataFeedGranularityType.DAILY))
    .setSchema(new DataFeedSchema(
        Arrays.asList(
            new DataFeedMetric("cost"),
            new DataFeedMetric("revenue")
        )).setDimensions(
        Arrays.asList(
            new DataFeedDimension("city"),
            new DataFeedDimension("category")
        ))
    )
    .setIngestionSettings(new DataFeedIngestionSettings(OffsetDateTime.parse("2020-01-01T00:00:00Z")))
    .setOptions(new DataFeedOptions()
        .setDescription("data feed description")
        .setRollupSettings(new DataFeedRollupSettings()
            .setRollupType(DataFeedRollupType.AUTO_ROLLUP)));
final DataFeed createdSqlDataFeed = metricsAdvisorAdminClient.createDataFeed(dataFeed);

System.out.printf("Data feed Id : %s%n", createdSqlDataFeed.getId());
System.out.printf("Data feed name : %s%n", createdSqlDataFeed.getName());
System.out.printf("Is the query user is one of data feed administrator : %s%n", createdSqlDataFeed.isAdmin());
System.out.printf("Data feed created time : %s%n", createdSqlDataFeed.getCreatedTime());
System.out.printf("Data feed granularity type : %s%n",
    createdSqlDataFeed.getGranularity().getGranularityType());
System.out.printf("Data feed granularity value : %d%n",
    createdSqlDataFeed.getGranularity().getCustomGranularityValue());
System.out.println("Data feed related metric Ids:");
dataFeed.getMetricIds().forEach((metricId, metricName)
    -> System.out.printf("Metric Id : %s, Metric Name: %s%n", metricId, metricName));
System.out.printf("Data feed source type: %s%n", createdSqlDataFeed.getSourceType());

if (SQL_SERVER_DB == createdSqlDataFeed.getSourceType()) {
    System.out.printf("Data feed sql server query: %s%n",
        ((SqlServerDataFeedSource) createdSqlDataFeed.getSource()).getQuery());
}

Überprüfen des Erfassungsstatus

In diesem Beispiel wird der Erfassungsstatus einer zuvor bereitgestellten Datenfeedquelle überprüft.

String dataFeedId = "3d48er30-6e6e-4391-b78f-b00dfee1e6f5";

metricsAdvisorAdminClient.listDataFeedIngestionStatus(
    dataFeedId,
    new ListDataFeedIngestionOptions(
        OffsetDateTime.parse("2020-01-01T00:00:00Z"),
        OffsetDateTime.parse("2020-09-09T00:00:00Z"))
).forEach(dataFeedIngestionStatus -> {
    System.out.printf("Message : %s%n", dataFeedIngestionStatus.getMessage());
    System.out.printf("Timestamp value : %s%n", dataFeedIngestionStatus.getTimestamp());
    System.out.printf("Status : %s%n", dataFeedIngestionStatus.getStatus());
});

Konfigurieren der Anomalieerkennung

Dieses Beispiel veranschaulicht, wie ein Benutzer für seine Daten eine Konfiguration für die Anomalieerkennung festlegen kann.

String metricId = "3d48er30-6e6e-4391-b78f-b00dfee1e6f5";

ChangeThresholdCondition changeThresholdCondition = new ChangeThresholdCondition(
    20,
    10,
    true,
    AnomalyDetectorDirection.BOTH,
    new SuppressCondition(1, 2));

HardThresholdCondition hardThresholdCondition = new HardThresholdCondition(
    AnomalyDetectorDirection.DOWN,
    new SuppressCondition(1, 1))
    .setLowerBound(5.0);

SmartDetectionCondition smartDetectionCondition = new SmartDetectionCondition(
    10.0,
    AnomalyDetectorDirection.UP,
    new SuppressCondition(1, 2));

final AnomalyDetectionConfiguration anomalyDetectionConfiguration =
    metricsAdvisorAdminClient.createDetectionConfig(
        metricId,
        new AnomalyDetectionConfiguration("My dataPoint anomaly detection configuration")
            .setDescription("anomaly detection config description")
            .setWholeSeriesDetectionCondition(
                new MetricWholeSeriesDetectionCondition()
                    .setChangeThresholdCondition(changeThresholdCondition)
                    .setHardThresholdCondition(hardThresholdCondition)
                    .setSmartDetectionCondition(smartDetectionCondition)
                    .setConditionOperator(DetectionConditionOperator.OR))
    );

Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen

In diesem Beispiel wird ein E-Mail-Hook erstellt, über den Warnungen zu Anomalieincidents empfangen werden.

NotificationHook emailNotificationHook = new EmailNotificationHook("email Hook")
    .setDescription("my email Hook")
    .setEmailsToAlert(Collections.singletonList("alertme@alertme.com"))
    .setExternalLink("https://adwiki.azurewebsites.net/articles/howto/alerts/create-hooks.html");

final NotificationHook notificationHook = metricsAdvisorAdminClient.createHook(emailNotificationHook);
EmailNotificationHook createdEmailHook = (EmailNotificationHook) notificationHook;
System.out.printf("Email Hook Id: %s%n", createdEmailHook.getId());
System.out.printf("Email Hook name: %s%n", createdEmailHook.getName());
System.out.printf("Email Hook description: %s%n", createdEmailHook.getDescription());
System.out.printf("Email Hook external Link: %s%n", createdEmailHook.getExternalLink());
System.out.printf("Email Hook emails to alert: %s%n",
    String.join(",", createdEmailHook.getEmailsToAlert()));

Konfigurieren einer Anomaliewarnungskonfiguration

In diesem Beispiel wird veranschaulicht, wie ein Benutzer eine Warnungskonfiguration für erkannte Anomalien in seinen Daten festlegen kann.

String detectionConfigurationId1 = "9ol48er30-6e6e-4391-b78f-b00dfee1e6f5";
String detectionConfigurationId2 = "3e58er30-6e6e-4391-b78f-b00dfee1e6f5";
String hookId1 = "5f48er30-6e6e-4391-b78f-b00dfee1e6f5";
String hookId2 = "8i48er30-6e6e-4391-b78f-b00dfee1e6f5";

final AnomalyAlertConfiguration anomalyAlertConfiguration
    = metricsAdvisorAdminClient.createAlertConfig(
        new AnomalyAlertConfiguration("My anomaly alert config name")
            .setDescription("alert config description")
            .setMetricAlertConfigurations(
                Arrays.asList(
                    new MetricAlertConfiguration(detectionConfigurationId1,
                        MetricAnomalyAlertScope.forWholeSeries()),
                    new MetricAlertConfiguration(detectionConfigurationId2,
                        MetricAnomalyAlertScope.forWholeSeries())
                        .setAlertConditions(new MetricAnomalyAlertConditions()
                            .setSeverityRangeCondition(new SeverityCondition(AnomalySeverity.HIGH,
                                AnomalySeverity.HIGH)))
                ))
            .setCrossMetricsOperator(MetricAlertConfigurationsOperator.AND)
            .setHookIdsToAlert(Arrays.asList(hookId1, hookId2)));

Abfragen von Anomalieerkennungsergebnissen

In diesem Beispiel wird veranschaulicht, wie ein Benutzer Warnungen abfragen kann, die für eine Anomalieerkennungskonfiguration ausgelöst wurden, und Anomalien für diese Anomalie Abrufen kannAlert.

String alertConfigurationId = "9ol48er30-6e6e-4391-b78f-b00dfee1e6f5";
final OffsetDateTime startTime = OffsetDateTime.parse("2020-01-01T00:00:00Z");
final OffsetDateTime endTime = OffsetDateTime.parse("2020-09-09T00:00:00Z");
metricsAdvisorClient.listAlerts(
    alertConfigurationId,
        startTime, endTime)
    .forEach(alert -> {
        System.out.printf("AnomalyAlert Id: %s%n", alert.getId());
        System.out.printf("AnomalyAlert created on: %s%n", alert.getCreatedTime());

        // List anomalies for returned alerts
        metricsAdvisorClient.listAnomaliesForAlert(
            alertConfigurationId,
            alert.getId())
            .forEach(anomaly -> {
                System.out.printf("DataPoint Anomaly was created on: %s%n", anomaly.getCreatedTime());
                System.out.printf("DataPoint Anomaly severity: %s%n", anomaly.getSeverity().toString());
                System.out.printf("DataPoint Anomaly status: %s%n", anomaly.getStatus());
                System.out.printf("DataPoint Anomaly related series key: %s%n", anomaly.getSeriesKey().asMap());
            });
    });

Problembehandlung

Allgemein

Metrics Advisor-Clients lösen [Ausnahmen][http_response_exception] aus HttpResponseException . Wenn Sie beispielsweise versuchen, eine nicht vorhandene Feedback-ID anzugeben, wird ein HttpResponseException mit einem Fehler ausgelöst, der die Fehlerursache angibt. Im folgenden Codeausschnitt wird der Fehler ordnungsgemäß behandelt, indem die Ausnahme abgefangen wird und zusätzliche Fehlerinformationen angezeigt werden.

try {
    metricsAdvisorClient.getFeedback("non_existing_feedback_id");
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

Aktivieren der Clientprotokollierung

Azure SDKs für Java bieten eine konsistente Protokollierung, die bei der Problembehandlung von Anwendungsfehlern und deren Lösung hilft. Die erstellten Protokolle erfassen den Flow einer Anwendung, bevor sie den Endzustand erreichen. Dies trägt zur Ermittlung der Grundursache bei. Informationen zum Aktivieren der Protokollierung finden Sie im Protokollierungswiki.

HTTP-Standardclient

Alle Clientbibliotheken verwenden standardmäßig den Netty-HTTP-Client. Durch Hinzufügen der obigen Abhängigkeit wird die Clientbibliothek automatisch für die Verwendung des Netty-HTTP-Clients konfiguriert. Das Konfigurieren oder Ändern des HTTP-Clients wird detailliert im Wiki zu HTTP-Clients beschrieben.

Nächste Schritte

Weitere Informationen finden Sie in der Infodatei zu den Beispielen.

Asynchrone APIs

Alle bisher gezeigten Beispiele haben synchrone APIs verwendet, aber wir bieten auch vollständige Unterstützung für asynchrone APIs. Sie müssen verwenden MetricsAdvisorAsyncClient

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorAsyncClient metricsAdvisorAsyncClient = new MetricsAdvisorClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildAsyncClient();

Zusätzliche Dokumentation

Eine ausführlichere Dokumentation zu Azure Cognitive Services Metrics Advisor finden Sie in der Dokumentation zu Metrics Advisor.

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

Aufrufe

Freigeben über