Partager via

Bibliothèque de client Azure Metrics Advisor pour Java - version 1.1.19

  • Article

Azure Metrics Advisor est un nouveau service cognitif qui utilise l’IA décisionnelle basée sur des séries chronologiques pour identifier et aider à résoudre les incidents de services en ligne, et surveiller l’intégrité de l’entreprise en automatisant la tranche et les dés des données métierFeedMetrics.

| Code sourcePackage (Maven) | Documentation de référence sur les | APIDocumentation | produitÉchantillons

Prise en main

Prérequis

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-ai-metricsadvisor</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. Note: Cette version cible l’API du service Azure Metrics Advisor version v1.0.

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

Créer une ressource Metrics Advisor

Authentifier le client

Pour interagir avec le service Metrics Advisor, vous devez créer une instance du client Metrics Advisor. Les clients asynchrones et synchrones peuvent être créés à l’aide de MetricsAdvisorClientBuilder. L’appel buildClient() crée le client synchrone, tandis que l’appel buildAsyncClient crée son équivalent asynchrone.

Recherche du point de terminaison

Vous trouverez le point de terminaison de votre ressource Metric Advisor dans le portail Azure ou Azure CLI.

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

Créer un client MetricsAdvisor à l’aide de MetricsAdvisorKeyCredential

Vous aurez besoin de deux clés pour authentifier le client :

  • Clé d’abonnement à votre ressource Metrics Advisor. Vous la trouverez dans la section Clés et point de terminaison de votre ressource dans le portail Azure.
  • Clé API de votre instance Metrics Advisor. Vous pouvez le trouver sur le portail web de Metrics Advisor, dans clés API dans le menu de navigation de gauche.

Une fois que vous avez les deux clés et le point de terminaison, vous pouvez utiliser la MetricsAdvisorKeyCredential classe pour authentifier les clients comme suit :

Créer un client Metrics Advisor à l’aide de MetricsAdvisorKeyCredential

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

Créer un client Metrics Administration à l’aide de MetricsAdvisorKeyCredential

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

Créer un client MetricsAdvisor à l’aide d’Azure Service Directory

Le Kit de développement logiciel (SDK) Azure pour Java prend en charge un package Azure Identity, ce qui facilite l’obtention des informations d’identification à partir de Plateforme d'identités Microsoft.

L’authentification avec AAD nécessite une configuration initiale :

  • Ajouter le package Azure Identity
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.7.3</version>
</dependency>

Après la configuration, vous pouvez choisir le type d’informations d’identification à utiliser à partir d’azure.identity. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client : 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.

L’autorisation est plus simple à l’aide de DefaultAzureCredential. Il trouve les meilleures informations d’identification à utiliser dans son environnement d’exécution. Pour plus d’informations sur l’utilisation de l’autorisation Azure Active Directory avec Metrics Advisor, consultez la documentation associée.

Créer un client Metrics Advisor à l’aide de l’authentification AAD

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

Créer un client Metrics Administration à l’aide de l’authentification AAD

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

Concepts clés

MetricsAdvisorClient

MetricsAdvisorClient aide à :

  • Diagnostiquer les anomalies et les incidents et faciliter l’analyse de la cause racine des incidents.
  • Récupérez les données de série chronologique d’origine et les données de série chronologique enrichies par le service.
  • Envoyer des alertes en temps réel via plusieurs hooks de notification.
  • Ajustez la détection d’anomalies/d’incidents à l’aide de commentaires pour paramétrer votre modèle.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient vous permet de

  • Gérer des flux de données
  • Répertorier les métriques disponibles et leurs configurations de détection
  • Affiner les configurations de détection d’anomalie
  • Configurer les configurations d’alerte d’anomalie
  • Gérer les hooks de notification

Flux de données

Un flux de données est ce que Metrics Advisor ingère à partir de la source de données spécifiée par l’utilisateur, telle que le flux de structure Cosmos, le résultat de la requête SQL, etc. Il contient des lignes d’horodatages, zéro ou plusieurs dimensions, une ou plusieurs métriques. Par conséquent, plusieurs métriques peuvent partager la même source de données et même le même flux de données.

Métrique de flux de données

Une métrique est une mesure quantifiable utilisée pour suivre et évaluer la status d’un processus métier spécifique. Il peut s’agir d’une combinaison de plusieurs valeurs de série chronologique divisées par dimensions, par exemple le nombre d’utilisateurs pour un marché web vertical et en-us.

Dimension de flux de données

Une dimension est une ou plusieurs valeurs catégorielles du flux de données fourni. Une combinaison de ces valeurs identifie une série chronologique particulière à une seule dimension, par exemple : pays, langue, abonné, etc.

Série de métriques

La série de métriques est une série de points de données indexés (ou répertoriés ou graphiques) dans l’ordre temporel. Le plus souvent, une série chronologique est une séquence effectuée à des points successifs à intervalles identiques dans le temps. Par conséquent, il s’agit d’une séquence de données à temps discret.

Configuration de la détection des anomalies

Une configuration de détection d’anomalie est une configuration fournie pour une série chronologique afin d’identifier si le point de données est détecté en tant qu’anomalie. Une métrique peut appliquer une ou plusieurs configurations de détection. Bien qu’une configuration de détection par défaut soit automatiquement appliquée à chaque métrique (nommée « Par défaut »), nous pouvons régler les modes de détection utilisés sur nos données en créant une configuration de détection d’anomalie personnalisée.

Incident d’anomalie

Les incidents sont générés pour les séries lorsqu’il y a une anomalie en fonction des configurations de détection d’anomalie appliquées. Le service Metrics Advisor regroupe une série d’anomalies au sein d’une métrique dans un incident.

Alerte d’anomalie

Les alertes d’anomalie peuvent être configurées pour être déclenchées lorsque certaines anomalies sont satisfaites. Vous pouvez définir plusieurs alertes avec des paramètres différents. Par exemple, vous pouvez créer une anomalieAlerte pour les anomalies ayant un impact moindre sur l’entreprise, et une autre pour les alertes plus importantes.

Notification Hook

Un hook de notification est le point d’entrée qui permet aux utilisateurs de s’abonner à des alertes en temps réel. Ces alertes sont envoyées sur Internet à l’aide d’un hook.

Exemples

Ajouter un flux de données à partir d’un exemple ou d’une source de données

Cet exemple ingère les données de source de flux de données spécifiées par SQLServerDataFeedSource l’utilisateur dans le service.

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

Vérifier l’état d’ingestion

Cet exemple vérifie l’état d’ingestion d’une source de flux de données précédemment fournie.

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

Paramétrer la configuration de la détection des anomalies

Cet exemple montre comment un utilisateur peut configurer une configuration de détection des anomalies pour ses données.

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

Ajouter des hooks pour recevoir des alertes d’anomalie

Cet exemple crée un hook par e-mail qui reçoit des alertes d’incident d’anomalie.

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

Configurer une configuration d’alerte d’anomalie

Cet exemple montre comment un utilisateur peut configurer une configuration d’alerte pour les anomalies détectées dans ses données.

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

Interroger les résultats de la détection des anomalies

Cet exemple montre comment un utilisateur peut interroger des alertes déclenchées pour une configuration de détection d’anomalie et obtenir des anomalies pour cette anomalieAlert.

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

Dépannage

Général

Les clients Metrics Advisor lèvent HttpResponseException [exceptions][http_response_exception]. Par exemple, si vous essayez de fournir un ID de commentaires non existant, une HttpResponseException erreur est générée avec une erreur indiquant la cause de l’échec. Dans l’extrait de code suivant, l’erreur est gérée correctement via l’interception de l’exception et en affichant des informations supplémentaires sur l’erreur en question.

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

Activer la journalisation du client

Les kits SDK Azure pour Java offrent un article de journalisation cohérent pour faciliter la résolution des erreurs d’application et accélérer leur résolution. Les journaux produits capturent le flux d’une application avant d’atteindre l’état terminal pour faciliter la localisation du problème racine. Consultez le wiki de journalisation pour obtenir des conseils sur l’activation de la journalisation.

Client HTTP par défaut

Toutes les bibliothèques de client utilisent par défaut le client HTTP Netty. L’ajout de la dépendance ci-dessus configure automatiquement la bibliothèque de client pour utiliser le client HTTP Netty. La configuration ou la modification du client HTTP sont détaillées dans le wiki pour clients HTTP.

Étapes suivantes

Pour plus d’informations, consultez les exemples LISEZ-MOI.

API asynchrones

Tous les exemples présentés jusqu’à présent utilisent des API synchrones, mais nous fournissons également une prise en charge complète des API asynchrones. Vous devez utiliser MetricsAdvisorAsyncClient

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

Documentation complémentaire

Pour obtenir une documentation plus complète sur Azure Cognitive Services Metrics Advisor, consultez la documentation metrics Advisor.

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

Impressions