Freigeben über

Azure Metrics Advisor-Clientbibliothek für JavaScript– Version 1.0.0

  • Artikel

Metrics Advisor ist Teil von Azure Cognitive Services und nutzt künstliche Intelligenz für die Datenüberwachung und Anomalieerkennung in Zeitreihendaten. Der Dienst automatisiert die Anwendung von Modellen auf Ihre Daten und bietet eine Reihe von APIs sowie einen webbasierten Arbeitsbereich für die Datenerfassung, Anomalieerkennung und Diagnose, die ganz ohne Machine Learning-Kenntnisse verwendet werden können. Metrics Advisor ermöglicht Folgendes:

  • Analysieren mehrdimensionaler Daten aus mehreren Datenquellen
  • Identifizieren und Korrelieren von Anomalien
  • Konfigurieren und Optimieren des für Ihre Daten verwendeten Anomalieerkennungsmodells
  • Diagnostizieren von Anomalien und Bereitstellen von Unterstützung bei der Ursachenanalyse

Wichtige Links:

Erste Schritte

Die derzeitig unterstützten Umgebungen

Ausführlichere Informationen finden Sie in der Supportrichtlinie.

Voraussetzungen

Wenn Sie die Azure CLI verwenden, ersetzen <your-resource-group-name> Sie und <your-resource-name> durch Ihre eigenen eindeutigen Namen:

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

Installieren Sie das Paket @azure/ai-metrics-advisor.

Installieren Sie die Azure Metrics Advisor-Clientbibliothek für JavaScript mit npm:

npm install @azure/ai-metrics-advisor

Erstellen und Authentifizieren MetricsAdvisorClient oder MetricsAdvisorAdministrationClient

Um ein Clientobjekt für den Zugriff auf die Metrics Advisor-API zu erstellen, benötigen Sie die endpoint ihrer Metrics Advisor-Ressource und eine credential. Die Metrics Advisor-Clients verwenden zur Authentifizierung einen Metrics Advisor-Schlüsselanmeldeinformationen.

Sie finden den Endpunkt für Ihre Metrics Advisor-Ressource entweder im Azure-Portal oder mithilfe des folgenden Azure CLI-Ausschnitts :

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

Verwenden von Abonnementschlüssel und API-Schlüssel

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

  • Der Abonnementschlüssel für Ihre Metrics Advisor-Ressource. Diese finden Sie im Abschnitt Schlüssel und Endpunkt Ihrer Ressource im Azure-Portal.
  • Der API-Schlüssel für Ihre Metrics Advisor-Instanz. Diesen finden Sie im Webportal für den Metrics Advisor im linken Navigationsmenü unter API-Schlüssel. Die URL Ihres Webportals finden Sie im Abschnitt Übersicht Ihrer Ressource im Azure-Portal.

Verwenden Sie das Azure-Portal , um zu Ihrer Metrics Advisor-Ressource zu navigieren und einen Abonnementschlüssel abzurufen, oder verwenden Sie den folgenden Azure CLI-Codeausschnitt :

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

Darüber hinaus benötigen Sie auch den Pro-Benutzer-API-Schlüssel aus Ihrem Metrics Advisor-Webportal.

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:

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

Verwenden des Azure-Dienstverzeichnisses

Die API-Schlüsselautorisierung wird in den meisten Beispielen verwendet, aber Sie können den Client auch mit Azure Active Directory mithilfe der Azure Identity-Bibliothek authentifizieren. Um den unten gezeigten DefaultAzureCredential-Anbieter oder andere Anmeldeinformationsanbieter zu verwenden, die mit dem Azure SDK bereitgestellt werden, installieren Sie das @azure/identity Paket:

npm install @azure/identity

Um sich mit einem Dienstprinzipal zu authentifizieren, müssen Sie auch eine AAD-Anwendung registrieren und Zugriff auf Metrics Advisor gewähren, indem Sie Ihrem Dienstprinzipal die Rolle "Cognitive Services-Benutzer" zuweisen (Hinweis: Andere Rollen wie "Besitzer" erteilen nicht die erforderlichen Berechtigungen, nur "Cognitive Services-Benutzer" reicht aus, um die Beispiele und den Beispielcode auszuführen).

Legen Sie die Werte der Client-ID, mandanten-ID und des geheimen Clientschlüssels der AAD-Anwendung als Umgebungsvariablen fest: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. Wir unterstützen auch die Authentifizierung durch Azure Active Directoty-Anmeldeinformationen. Sie benötigen die Azure-Mandanten-ID, die Azure-Client-ID und den geheimen Azure-Clientschlüssel als Umgebungsvariablen.

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

Wichtige Begriffe

MetricsAdvisorClient

MetricsAdvisorClient ist die primäre Abfrageschnittstelle für Entwickler, die die Metrics Advisor-Clientbibliothek verwenden. Es bietet asynchrone Methoden für den Zugriff auf eine bestimmte Verwendung von Metrics Advisor, z. B. das Auflisten von Incidents, das Erneute Ermitteln von Ursachen für Vorfälle, das Abrufen von ursprünglichen Zeitreihendaten und Zeitreihendaten, die vom Dienst angereichert werden.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient ist die Schnittstelle, die für die Verwaltung von Entitäten in den Metrics Advisor-Ressourcen zuständig ist, z. B. verwalten von Datenfeeds, Anomalieerkennungskonfigurationen und Konfigurationen für Anomaliewarnungen.

Datenfeed

Ein Datenfeed umfasst die Daten, die von Metrics Advisor über Ihre Datenquelle erfasst werden, z. B. Cosmos DB oder eine SQL Server-Instanz. Ein Datenfeed enthält Zeilen mit den folgenden Informationen:

  • Timestamps
  • Null oder mehr Dimensionen
  • eine oder mehrere Measures

Metrik

Eine Metrik ist ein quantifizierbares Measure, das zum Überwachen und Bewerten des Status eines bestimmten Geschäftsprozesses verwendet wird. Hierbei kann es sich um eine Kombination aus mehreren Zeitreihen handeln, die in Dimensionen unterteilt sind. Eine Metrik vom Typ Webintegrität kann beispielsweise Dimensionen für die Benutzeranzahl und den US-amerikanischen Markt enthalten.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration ist für jede Zeitreihe erforderlich und bestimmt, ob ein Punkt in der Zeitreihe eine Anomalie ist.

Anomalie-& Incident

Nachdem eine Erkennungskonfiguration auf Metriken angewendet wurde, werden s generiert, AnomalyIncidentwenn eine Reihe darin einen DataPointAnomalyenthält.

Warnung

Sie können konfigurieren, welche Anomalien eine AnomalyAlertauslösen sollen. Sie können mehrere Warnungen mit unterschiedlichen Einstellungen festlegen. Sie können beispielsweise eine Warnung für Anomalien mit geringeren geschäftlichen Auswirkungen und eine weitere warnung für wichtigere Warnungen erstellen.

Hook

Mit Metrics Advisor können Sie Echtzeitwarnungen erstellen und abonnieren. Diese Warnungen werden mithilfe eines Benachrichtigungshooks über das Internet gesendet.

Eine umfassende Liste der Konzepte finden Sie auf der Dokumentationsseite metrikspezifisches Glossar .

Beispiele

Der folgende Abschnitt enthält mehrere JavaScript-Codeausschnitte, die gängige Muster veranschaulichen, die in den Metrics Advisor-Clientbibliotheken verwendet werden.

Hinzufügen eines Datenfeeds aus einer Beispieldatenquelle

Metrics Advisor unterstützt die Verbindung von unterschiedlichen Typen von Datenquellen. Hier ist ein Beispiel für die Erfassung von Daten aus SQL Server angegeben.

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

Überprüfen des Erfassungsstatus

Nach dem Starten der Datenerfassung können wir den Erfassungsstatus überprüfen.

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

Konfigurieren der Anomalieerkennung

Wir benötigen eine Konfiguration für die Anomalieerkennung, um zu bestimmen, ob es sich bei einem Punkt der Zeitreihe um eine Anomalie handelt. Auf jede Metrik wird automatisch eine Standardkonfiguration für die Erkennung angewendet. Sie können die für Ihre Daten verwendeten Erkennungsmodi aber optimieren, indem Sie eine angepasste Konfiguration für die Anomalieerkennung erstellen.

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

Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen

Wir verwenden Hooks, um Echtzeitwarnungen zu abonnieren. In diesem Beispiel erstellen wir einen Webhook für den Metrics Advisor-Dienst, an den die Warnung per POST-Vorgang gesendet werden kann.

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

Konfigurieren von Warnungen

Anschließend konfigurieren wir, unter welchen Bedingungen eine Warnung ausgelöst werden muss und welche Hooks die Warnung senden sollen.

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

Abfragen von Anomalieerkennungsergebnissen

Wir können die Warnungen und Anomalien abfragen.

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

Problembehandlung

Protokollierung

Die Aktivierung der Protokollierung kann hilfreiche Informationen über Fehler aufdecken. Um ein Protokoll von HTTP-Anforderungen und -Antworten anzuzeigen, legen Sie die Umgebungsvariable AZURE_LOG_LEVEL auf info fest. Alternativ kann die Protokollierung zur Laufzeit aktiviert werden, indem Sie setLogLevel in @azure/logger aufrufen:

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

setLogLevel("info");

Ausführlichere Anweisungen zum Aktivieren von Protokollen finden Sie in der Paketdokumentation zu @azure/logger.

Nächste Schritte

Ausführliche Beispiele zur Verwendung dieser Bibliothek finden Sie im Beispielverzeichnis .

Mitwirken

Wenn Sie zu dieser Bibliothek beitragen möchten, lesen Sie den leitfaden, der mitwirkend ist, um mehr über das Erstellen und Testen zu erfahren.
den Code.

Aufrufe