Bibliothèque cliente Azure Metrics Advisor pour JavaScript - version 1.0.0

Article
04/05/2023

Metrics Advisor fait partie d’Azure Cognitive Services, qui utilise l’intelligence artificielle pour surveiller les données et détecter les anomalies dans des données de série chronologique. Le service automatise le processus d’application de modèles à vos données et fournit un ensemble d’API et un espace de travail web pour l’ingestion des données, la détection des anomalies et les diagnostics, sans avoir besoin de connaître le machine learning. Utilisez Metrics Advisor pour :

Analyser des données multidimensionnelles à partir de plusieurs sources de données
Identifier et corréler les anomalies
Configurer et ajuster le modèle de détection d’anomalies utilisé sur vos données
Diagnostiquer les anomalies et aider à analyser la cause racine.

Liens clés :

Prise en main

Environnements actuellement pris en charge

Versions LTS de Node.js
Dernières versions de Safari, Chrome, Edge et Firefox.

Pour plus d’informations, consultez notre politique de support .

Prérequis

Un abonnement Azure.
Une ressource Cognitive Services ou Metrics Advisor existante. Si vous devez créer la ressource, vous pouvez utiliser le portail Azure ou Azure CLI.

Si vous utilisez Azure CLI, remplacez <your-resource-group-name> et <your-resource-name> par vos propres noms uniques :

az cognitiveservices account create --kind MetricsAdvisor --resource-group <your-resource-group-name> --name <your-resource-name> --sku <sku level> --location <location>

Installez le package `@azure/ai-metrics-advisor`

Installez la bibliothèque cliente Azure Metrics Advisor pour JavaScript avec npm:

npm install @azure/ai-metrics-advisor

Créer et authentifier `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`

Pour créer un objet client afin d’accéder à l’API Metrics Advisor, vous aurez besoin de votre endpoint ressource Metrics Advisor et d’un credential. Les clients Metrics Advisor utilisent des informations d’identification de clé Metrics Advisor pour s’authentifier.

Vous pouvez trouver le point de terminaison de votre ressource Metrics Advisor dans le portail Azure ou à l’aide de l’extrait de code Azure CLI ci-dessous :

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

Utilisation d’une clé d’abonnement et d’une clé API

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

Clé d’abonnement à votre ressource Metrics Advisor. Vous pouvez le trouver dans la section Clés et point de terminaison de votre ressource dans le portail Azure.
Clé API de votre instance Metrics Advisor. Vous la trouverez dans le portail web de Metrics Advisor, dans Clés API, dans le menu de navigation de gauche. L’URL de votre portail web se trouve dans la section Vue d’ensemble de votre ressource dans le portail Azure.

Utilisez le portail Azure pour accéder à votre ressource Metrics Advisor et récupérer une clé d’abonnement, ou utilisez l’extrait de code Azure CLI ci-dessous :

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

En outre, vous aurez également besoin de la clé API par utilisateur à partir de votre portail web Metrics Advisor.

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 :

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

const credential = new MetricsAdvisorKeyCredential("<subscription Key>", "<API key>");

const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

Utilisation d’Azure Service Directory

L’autorisation de clé API est utilisée dans la plupart des exemples, mais vous pouvez également authentifier le client 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, installez le @azure/identity package :

npm install @azure/identity

Pour vous authentifier à l’aide d’un principal de service, vous devez également inscrire une application AAD et accorder l’accès à Metrics Advisor en attribuant le rôle « Utilisateur Cognitive Services » à votre principal de service (remarque : d’autres rôles tels que « Propriétaire » n’accordent pas les autorisations nécessaires, seul « Utilisateur Cognitive Services » suffit pour exécuter les exemples et l’exemple de code).

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. Nous prenons également en charge l’authentification par Les informations d’identification Azure Active Directoty. Vous aurez besoin de l’ID de locataire Azure, de l’ID client Azure et de la clé secrète client Azure en tant que variables d’environnement.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorClient,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");
import { DefaultAzureCredential } from "@azure/identity";
const credential = new DefaultAzureCredential();
const client = new MetricsAdvisorClient("<endpoint>", credential);
const adminClient = new MetricsAdvisorAdministrationClient("<endpoint>", credential);

Concepts clés

MetricsAdvisorClient

MetricsAdvisorClient est l’interface d’interrogation principale pour les développeurs qui utilisent la bibliothèque cliente Metrics Advisor. Il fournit des méthodes asynchrones pour accéder à une utilisation spécifique de Metrics Advisor, comme la liste des incidents, la résolution des causes racines des incidents, la récupération des données de série chronologique d’origine et des données de série chronologique enrichies par le service.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient est l’interface responsable de la gestion des entités dans les ressources Metrics Advisor, telles que la gestion des flux de données, des configurations de détection d’anomalies, des configurations d’alerte d’anomalies.

Flux de données

Un flux de données est ce que Metrics Advisor ingère de votre source de données, par exemple Cosmos DB ou SQL Server. Un flux de données contient des lignes de :

horodatage
zéro ou plusieurs dimensions
une ou plusieurs mesures

Métrique

Une métrique est une mesure quantifiable utilisée pour analyser et évaluer l’état d’un processus d’entreprise spécifique. Il peut s’agir d’une combinaison de plusieurs valeurs de séries chronologiques divisées en dimensions. Par exemple, une métrique d’intégrité du Web peut contenir des dimensions pour le nombre d’utilisateurs et le marché en-US.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration est requis pour chaque série chronologique et détermine si un point de la série chronologique est une anomalie.

Incident de & d’anomalie

Une fois qu’une configuration de détection a été appliquée aux métriques, AnomalyIncidentles s sont générés chaque fois qu’une série comporte un DataPointAnomaly.

Alerte

Vous pouvez configurer les anomalies qui doivent déclencher un AnomalyAlert. Vous pouvez définir plusieurs alertes avec des paramètres différents. Par exemple, vous pouvez créer une alerte pour les anomalies ayant un impact moindre sur l’entreprise et une autre pour les alertes plus importantes.

Hook

Metrics Advisor vous permet de créer des alertes en temps réel et de vous s’y abonner. Ces alertes sont envoyées via Internet à l’aide d’un hook de notification.

Pour obtenir une liste complète des concepts, reportez-vous à la page de documentation du glossaire des métriques .

Exemples

La section suivante fournit plusieurs extraits de code JavaScript illustrant les modèles courants utilisés dans les bibliothèques clientes Metrics Advisor.

Ajouter un flux de données à partir d’un exemple de source de données
Check ingestion status
Configurer la configuration de la détection des anomalies
Ajouter des hooks pour recevoir des alertes d’anomalie
Configurer la configuration des alertes
Résultats de la détection des anomalies de requête

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

Metrics Advisor prend en charge la connexion de différents types de sources de données. Voici un exemple d’ingestion de données à partir de SQL Server.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const sqlServerConnectionString =
    process.env["METRICS_ADVISOR_SQL_SERVER_CONNECTION_STRING"] ||
    "<connection string to SQL Server>";
  const sqlServerQuery =
    process.env["METRICS_ADVISOR_AZURE_SQL_SERVER_QUERY"] || "<SQL Server query to retrive data>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const created = await createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery);
  console.log(`Data feed created: ${created.id}`);
}

async function createDataFeed(adminClient, sqlServerConnectionString, sqlServerQuery) {
  console.log("Creating Datafeed...");
  const dataFeed = {
    name: "test_datafeed_" + new Date().getTime().toString(),
    source: {
      dataSourceType: "SqlServer",
      connectionString: sqlServerConnectionString,
      query: sqlServerQuery,
      authenticationType: "Basic"
    },
    granularity: {
      granularityType: "Daily"
    },
    schema: {
      metrics: [
        {
          name: "revenue",
          displayName: "revenue",
          description: "Metric1 description"
        },
        {
          name: "cost",
          displayName: "cost",
          description: "Metric2 description"
        }
      ],
      dimensions: [
        { name: "city", displayName: "city display" },
        { name: "category", displayName: "category display" }
      ],
      timestampColumn: null
    },
    ingestionSettings: {
      ingestionStartTime: new Date(Date.UTC(2020, 5, 1)),
      ingestionStartOffsetInSeconds: 0,
      dataSourceRequestConcurrency: -1,
      ingestionRetryDelayInSeconds: -1,
      stopRetryAfterInSeconds: -1
    },
    rollupSettings: {
      rollupType: "AutoRollup",
      rollupMethod: "Sum",
      rollupIdentificationValue: "__CUSTOM_SUM__"
    },
    missingDataPointFillSettings: {
      fillType: "SmartFilling"
    },
    accessMode: "Private",
    admins: ["xyz@example.com"]
  };
  const result = await adminClient.createDataFeed(dataFeed);

  return result;
}

Vérifier l’état d’ingestion

Après avoir démarré l’ingestion des données, nous pouvons vérifier l’état d’ingestion.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const dataFeedId = process.env["METRICS_DATAFEED_ID"] || "<data feed id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  await checkIngestionStatus(
    adminClient,
    dataFeedId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );
}

async function checkIngestionStatus(adminClient, datafeedId, startTime, endTime) {
  // This shows how to use for-await-of syntax to list status
  console.log("Checking ingestion status...");
  const iterator = adminClient.listDataFeedIngestionStatus(datafeedId, startTime, endTime);
  for await (const status of iterator) {
    console.log(`  [${status.timestamp}] ${status.status} - ${status.message}`);
  }
}

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

Nous avons besoin d’une configuration de détection d’anomalie pour déterminer si un point dans la série chronologique est une anomalie. Une configuration de détection par défaut est automatiquement appliquée à chaque métrique, mais vous pouvez ajuster les modes de détection utilisés sur vos données en créant une configuration de détection des anomalies personnalisée.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const metricId = process.env["METRICS_ADVISOR_METRIC_ID"] || "<metric id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);

  const detectionConfig = await configureAnomalyDetectionConfiguration(adminClient, metricId);
  console.log(`Detection configuration created: ${detectionConfig.id}`);
}

async function configureAnomalyDetectionConfiguration(adminClient, metricId) {
  console.log(`Creating an anomaly detection configuration on metric '${metricId}'...`);
  const anomalyConfig = {
    name: "test_detection_configuration" + new Date().getTime().toString(),
    metricId,
    wholeSeriesDetectionCondition: {
      smartDetectionCondition: {
        sensitivity: 100,
        anomalyDetectorDirection: "Both",
        suppressCondition: {
          minNumber: 1,
          minRatio: 1
        }
      }
    },
    description: "Detection configuration description"
  };
  return await adminClient.createDetectionConfig(anomalyConfig);
}

Ajouter des hooks pour recevoir des alertes d’anomalie

Nous utilisons des hooks s’abonnent aux alertes en temps réel. Dans cet exemple, nous créons un webhook pour le service Metrics Advisor sur lequel l’alerte doit être publiée.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const hook = await createWebhookHook(adminClient);
  console.log(`Webhook hook created: ${hook.id}`);
}

async function createWebhookHook(adminClient) {
  console.log("Creating a webhook hook");
  const hook = {
    hookType: "Webhook",
    name: "web hook " + new Date().getTime().toString(),
    description: "description",
    hookParameter: {
      endpoint: "https://example.com/handleAlerts",
      username: "username",
      password: "password"
      // certificateKey: "certificate key",
      // certificatePassword: "certificate password"
    }
  };

  return await adminClient.createHook(hook);
}

Paramétrer la configuration des alertes

Ensuite, nous allons configurer dans quelles conditions une alerte doit être déclenchée et quels crochets pour envoyer l’alerte.

const {
  MetricsAdvisorKeyCredential,
  MetricsAdvisorAdministrationClient
} = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const detectionConfigId = process.env["METRICS_ADVISOR_DETECTION_CONFIG_ID"] || "<detection id>";
  const hookId = process.env["METRICS_ADVISOR_HOOK_ID"] || "<hook id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const adminClient = new MetricsAdvisorAdministrationClient(endpoint, credential);
  const alertConfig = await configureAlertConfiguration(adminClient, detectionConfigId, [hookId]);
  console.log(`Alert configuration created: ${alertConfig.id}`);
}

async function configureAlertConfiguration(adminClient, detectionConfigId, hookIds) {
  console.log("Creating a new alerting configuration...");
  const anomalyAlertConfig = {
    name: "test_alert_config_" + new Date().getTime().toString(),
    crossMetricsOperator: "AND",
    metricAlertConfigurations: [
      {
        detectionConfigurationId: detectionConfigId,
        alertScope: {
          scopeType: "All"
        },
        alertConditions: {
          severityCondition: { minAlertSeverity: "Medium", maxAlertSeverity: "High" }
        },
        snoozeCondition: {
          autoSnooze: 0,
          snoozeScope: "Metric",
          onlyForSuccessive: true
        }
      }
    ],
    hookIds,
    description: "Alerting config description"
  };
  return await adminClient.createAlertConfig(anomalyAlertConfig);
}

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

Nous pouvons interroger les alertes et les anomalies.

const { MetricsAdvisorKeyCredential, MetricsAdvisorClient } = require("@azure/ai-metrics-advisor");

async function main() {
  // You will need to set these environment variables or edit the following values
  const endpoint = process.env["METRICS_ADVISOR_ENDPOINT"] || "<service endpoint>";
  const subscriptionKey = process.env["METRICS_ADVISOR_SUBSCRIPTION_KEY"] || "<subscription key>";
  const apiKey = process.env["METRICS_ADVISOR_API_KEY"] || "<api key>";
  const alertConfigId = process.env["METRICS_ADVISOR_ALERT_CONFIG_ID"] || "<alert config id>";
  const credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);

  const client = new MetricsAdvisorClient(endpoint, credential);

  const alerts = await queryAlerts(
    client,
    alertConfigId,
    new Date(Date.UTC(2020, 8, 1)),
    new Date(Date.UTC(2020, 8, 12))
  );

  if (alerts.length > 1) {
    // query anomalies using an alert id.
    await queryAnomaliesByAlert(client, alerts[0]);
  } else {
    console.log("No alerts during the time period");
  }
}

async function queryAlerts(client, alertConfigId, startTime, endTime) {
  let alerts = [];
  const iterator = client.listAlerts(alertConfigId, startTime, endTime, "AnomalyTime");
  for await (const alert of iterator) {
    alerts.push(alert);
  }

  return alerts;
}

async function queryAnomaliesByAlert(client, alert) {
  console.log(
    `Listing anomalies for alert configuration '${alert.alertConfigId}' and alert '${alert.id}'`
  );
  const iterator = client.listAnomaliesForAlert(alert);
  for await (const anomaly of iterator) {
    console.log(
      `  Anomaly ${anomaly.severity} ${anomaly.status} ${anomaly.seriesKey} ${anomaly.timestamp}`
    );
  }
}

Résolution des problèmes

Journalisation

L’activation de la journalisation peut vous aider à mieux comprendre les échecs. Pour avoir un journal des requêtes et réponses HTTP, définissez la variable d’environnement AZURE_LOG_LEVEL sur info. Vous pouvez également activer la journalisation au moment de l’exécution en appelant setLogLevel dans @azure/logger :

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Pour obtenir des instructions plus détaillées sur l’activation des journaux, consultez les documents relatifs au package @azure/logger.

Étapes suivantes

Consultez le répertoire d’exemples pour obtenir des exemples détaillés sur l’utilisation de cette bibliothèque.

Contribution

Si vous souhaitez contribuer à cette bibliothèque, lisez le guide de contribution pour en savoir plus sur la façon de générer et de tester
le code.

Kit de développement logiciel (SDK) Microsoft Azure pour Javascript

Impressions

Partager via

Bibliothèque cliente Azure Metrics Advisor pour JavaScript - version 1.0.0

Prise en main

Environnements actuellement pris en charge

Prérequis

Installez le package `@azure/ai-metrics-advisor`

Créer et authentifier `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`

Utilisation d’une clé d’abonnement et d’une clé API

Utilisation d’Azure Service Directory

Concepts clés

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Flux de données

Métrique

AnomalyDetectionConfiguration

Incident de & d’anomalie

Alerte

Hook

Exemples

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

Vérifier l’état d’ingestion

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

Ajouter des hooks pour recevoir des alertes d’anomalie

Paramétrer la configuration des alertes

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

Résolution des problèmes

Journalisation

Étapes suivantes

Contribution

Ressources supplémentaires

Partager via

Bibliothèque cliente Azure Metrics Advisor pour JavaScript - version 1.0.0

Prise en main

Environnements actuellement pris en charge

Prérequis

Installez le package @azure/ai-metrics-advisor

Créer et authentifier MetricsAdvisorClient ou MetricsAdvisorAdministrationClient

Utilisation d’une clé d’abonnement et d’une clé API

Utilisation d’Azure Service Directory

Concepts clés

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Flux de données

Métrique

AnomalyDetectionConfiguration

Incident de & d’anomalie

Alerte

Hook

Exemples

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

Vérifier l’état d’ingestion

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

Ajouter des hooks pour recevoir des alertes d’anomalie

Paramétrer la configuration des alertes

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

Résolution des problèmes

Journalisation

Étapes suivantes

Contribution

Projets associés

Ressources supplémentaires

Installez le package `@azure/ai-metrics-advisor`

Créer et authentifier `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`