Azure Metrics Advisor-klientbibliotek för JavaScript – version 1.0.0

Artikel
04/05/2023

Metrics Advisor är en del av Azure Cognitive Services som använder AI för att utföra dataövervakning och avvikelseidentifiering i tidsseriedata. Tjänsten automatiserar processen med att tillämpa modeller på dina data och tillhandahåller en uppsättning API:er webbaserade arbetsyta för datainmatning, avvikelseidentifiering och diagnostik – utan att behöva känna till maskininlärning. Använd Metrics Advisor för att:

Analysera flerdimensionella data från flera datakällor
Identifiera och korrelera avvikelser
Konfigurera och finjustera modellen för avvikelseidentifiering som används för dina data
Diagnostisera avvikelser och hjälp med rotorsaksanalys.

Nyckellänkar:

Komma igång

Miljöer som stöds för närvarande

LTS-versioner av Node.js
De senaste versionerna av Safari, Chrome, Edge och Firefox.

Mer information finns i vår supportpolicy .

Förutsättningar

En Azure-prenumeration.
En befintlig Cognitive Services - eller Metrics Advisor-resurs. Om du behöver skapa resursen kan du använda Azure-portalen eller Azure CLI.

Om du använder Azure CLI ersätter <your-resource-group-name> du och <your-resource-name> med dina egna unika namn:

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

Installera `@azure/ai-metrics-advisor`-paketet

Installera Azure Metrics Advisor-klientbiblioteket för JavaScript med npm:

npm install @azure/ai-metrics-advisor

Skapa och autentisera `MetricsAdvisorClient` eller `MetricsAdvisorAdministrationClient`

Om du vill skapa ett klientobjekt för att få åtkomst till Metrics Advisor-API:et endpoint behöver du för din Metrics Advisor-resurs och en credential. Metrics Advisor-klienterna använder en Metrics Advisor-nyckelautentiseringsuppgift för att autentisera.

Du hittar slutpunkten för din Metrics Advisor-resurs antingen i Azure-portalen eller med hjälp av Azure CLI-kodfragmentet nedan:

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

Använda prenumerationsnyckel och API-nyckel

Du behöver två nycklar för att autentisera klienten:

Prenumerationsnyckeln för din Metrics Advisor-resurs. Du hittar detta i avsnittet Nycklar och slutpunkt för din resurs i Azure-portalen.
API-nyckeln för din Metrics Advisor-instans. Du hittar detta i webbportalen för Metrics Advisor i API-nycklar på den vänstra navigeringsmenyn. Url:en för webbportalen finns i avsnittet Översikt för din resurs i Azure-portalen.

Använd Azure-portalen för att bläddra till din Metrics Advisor-resurs och hämta en prenumerationsnyckel, eller använd Azure CLI-kodfragmentet nedan:

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

Dessutom behöver du api-nyckeln per användare från din Metrics Advisor-webbportal.

När du har de två nycklarna och slutpunkten kan du använda klassen för att autentisera MetricsAdvisorKeyCredential klienterna på följande sätt:

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

Använda Azure Service Directory

API-nyckelauktorisering används i de flesta exempel, men du kan även autentisera klienten med Azure Active Directory med hjälp av Azure Identity-biblioteket. Om du vill använda DefaultAzureCredential-providern som visas nedan eller andra leverantörer av autentiseringsuppgifter som medföljer Azure SDK installerar @azure/identity du paketet:

npm install @azure/identity

Om du vill autentisera med hjälp av ett huvudnamn för tjänsten måste du också registrera ett AAD-program och bevilja åtkomst till Metrics Advisor genom att tilldela rollen "Cognitive Services-användare" till tjänstens huvudnamn (obs! Andra roller som "Ägare" beviljar inte de behörigheter som krävs, endast "Cognitive Services-användare" räcker för att köra exemplen och exempelkoden).

Ange värdena för klient-ID, klient-ID och klienthemlighet för AAD-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. Vi stöder även autentisering av Azure Active Directoty-autentiseringsuppgifter. Du behöver Azure-klientorganisations-ID, Azure-klient-ID och Azure-klienthemlighet som miljövariabler.

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

Viktiga begrepp

MetricsAdvisorClient

MetricsAdvisorClient är det primära frågegränssnittet för utvecklare som använder Metrics Advisor-klientbiblioteket. Den tillhandahåller asynkrona metoder för att komma åt en specifik användning av Metrics Advisor, till exempel att lista incidenter, försöka hitta rotorsaker till incidenter, hämta ursprungliga tidsseriedata och tidsseriedata som berikas av tjänsten.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient är gränssnittet som ansvarar för att hantera entiteter i Metrics Advisor-resurserna, till exempel hantera datafeeds, konfigurationer för avvikelseidentifiering, konfigurationer för avisering av avvikelser.

Datafeed

Ett dataflöde är vad Metrics Advisor matar in från din datakälla, till exempel Cosmos DB eller en SQL-server. En datafeed innehåller rader med:

Tidsstämplar
noll eller fler dimensioner
ett eller flera mått

Metric

Ett mått är ett kvantifierbart mått som används för att övervaka och utvärdera status för en specifik affärsprocess. Det kan vara en kombination av flera tidsserievärden indelade i dimensioner. Ett webbhälsomått kan till exempel innehålla dimensioner för antalet användare och en-us-marknaden.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration krävs för varje tidsserie och avgör om en punkt i tidsserien är en avvikelse.

Avvikelse & incident

När en identifieringskonfiguration har tillämpats AnomalyIncidentpå mått genereras s när alla serier i den har en DataPointAnomaly.

Varning

Du kan konfigurera vilka avvikelser som ska utlösa en AnomalyAlert. Du kan ange flera aviseringar med olika inställningar. Du kan till exempel skapa en avisering för avvikelser med lägre affärspåverkan och en annan för viktigare aviseringar.

Krok

Med Metrics Advisor kan du skapa och prenumerera på realtidsaviseringar. Dessa aviseringar skickas via Internet med hjälp av en meddelandehook.

Se dokumentationssidan för metrics advisory glossary för en omfattande lista över begrepp.

Exempel

Följande avsnitt innehåller flera JavaScript-kodfragment som illustrerar vanliga mönster som används i Metrics Advisor-klientbiblioteken.

Lägga till ett dataflöde från en exempeldatakälla
Kontrollera datainmatningsstatus
Konfigurera konfiguration av avvikelseidentifiering
Lägga till krokar för att ta emot avvikelseaviseringar
Konfigurera aviseringskonfiguration
Fråga avvikelseidentifieringsresultat

Lägga till ett dataflöde från en exempeldatakälla

Metrics Advisor stöder anslutning av olika typer av datakällor. Här är ett exempel på hur du matar in data från 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;
}

Kontrollera datainmatningsstatus

När vi har startat datainmatningen kan vi kontrollera inmatningsstatusen.

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

Konfigurera konfiguration av avvikelseidentifiering

Vi behöver en konfiguration för avvikelseidentifiering för att avgöra om en punkt i tidsserien är en avvikelse. Även om en standardidentifieringskonfiguration tillämpas automatiskt på varje mått kan du justera de identifieringslägen som används för dina data genom att skapa en anpassad konfiguration för avvikelseidentifiering.

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

Lägga till krokar för att ta emot avvikelseaviseringar

Vi använder hooks för att prenumerera på realtidsaviseringar. I det här exemplet skapar vi en webhook för metrics advisor-tjänsten som aviseringen postas till.

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

Konfigurera aviseringskonfiguration

Sedan konfigurerar vi i vilka villkor en avisering måste utlösas och vilka hookar som ska skicka aviseringen.

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

Fråga avvikelseidentifieringsresultat

Vi kan köra frågor mot aviseringar och avvikelser.

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

Felsökning

Loggning

Aktivering av loggning kan hjälpa dig att hitta användbar information om fel. Om du vill se en logg över HTTP-begäranden och svar anger du AZURE_LOG_LEVEL miljövariabeln till info. Loggning kan också aktiveras vid körning genom att anropa setLogLevel i @azure/logger:

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

setLogLevel("info");

Mer detaljerade anvisningar om hur du aktiverar loggar finns i dokumentationen om @azure-/loggningspaket.

Nästa steg

Ta en titt på exempelkatalogen för detaljerade exempel på hur du använder det här biblioteket.

Bidra

Om du vill bidra till det här biblioteket kan du läsa bidragsguiden om du vill veta mer om hur du skapar och testar
koden.

Microsoft Azure SDK för Javascript

Visningar

Dela via

Azure Metrics Advisor-klientbibliotek för JavaScript – version 1.0.0

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Installera `@azure/ai-metrics-advisor`-paketet

Skapa och autentisera `MetricsAdvisorClient` eller `MetricsAdvisorAdministrationClient`

Använda prenumerationsnyckel och API-nyckel

Använda Azure Service Directory

Viktiga begrepp

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Datafeed

Metric

AnomalyDetectionConfiguration

Avvikelse & incident

Varning

Krok

Exempel

Lägga till ett dataflöde från en exempeldatakälla

Kontrollera datainmatningsstatus

Konfigurera konfiguration av avvikelseidentifiering

Lägga till krokar för att ta emot avvikelseaviseringar

Konfigurera aviseringskonfiguration

Fråga avvikelseidentifieringsresultat

Felsökning

Loggning

Nästa steg

Bidra

Ytterligare resurser

Dela via

Azure Metrics Advisor-klientbibliotek för JavaScript – version 1.0.0

Komma igång

Miljöer som stöds för närvarande

Förutsättningar

Installera @azure/ai-metrics-advisor-paketet

Skapa och autentisera MetricsAdvisorClient eller MetricsAdvisorAdministrationClient

Använda prenumerationsnyckel och API-nyckel

Använda Azure Service Directory

Viktiga begrepp

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Datafeed

Metric

AnomalyDetectionConfiguration

Avvikelse & incident

Varning

Krok

Exempel

Lägga till ett dataflöde från en exempeldatakälla

Kontrollera datainmatningsstatus

Konfigurera konfiguration av avvikelseidentifiering

Lägga till krokar för att ta emot avvikelseaviseringar

Konfigurera aviseringskonfiguration

Fråga avvikelseidentifieringsresultat

Felsökning

Loggning

Nästa steg

Bidra

Relaterade projekt

Ytterligare resurser

Installera `@azure/ai-metrics-advisor`-paketet

Skapa och autentisera `MetricsAdvisorClient` eller `MetricsAdvisorAdministrationClient`