Azure Metrics Advisor-Clientbibliothek für JavaScript– Version 1.0.0
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
- LTS-Versionen von Node.js
- Neueste Versionen von Safari, Chrome, Edge und Firefox.
Ausführlichere Informationen finden Sie in der Supportrichtlinie.
Voraussetzungen
- Ein Azure-Abonnement.
- Eine vorhandene Cognitive Services - oder Metrics Advisor-Ressource. Wenn Sie die Ressource erstellen müssen, können Sie das Azure-Portal oder die Azure CLI verwenden.
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, AnomalyIncident
wenn eine Reihe darin einen DataPointAnomaly
enthält.
Warnung
Sie können konfigurieren, welche Anomalien eine AnomalyAlert
auslö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
- Checken der Erfassungs-status
- Konfigurieren der Anomalieerkennungskonfiguration
- Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen
- Konfigurieren der Warnungskonfiguration
- Abfragen von Anomalieerkennungsergebnissen
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.
Verwandte Projekte
Azure SDK for JavaScript