Sdílet prostřednictvím

Klientská knihovna Azure Metrics Advisoru pro JavaScript – verze 1.0.0

  • Článek

Metrics Advisor je součástí služeb Azure Cognitive Services, které používají monitorování dat a detekci anomálií v datech časových řad pomocí AI. Služba automatizuje proces aplikování modelů na vaše data a poskytuje sadu webových pracovních prostorů rozhraní API pro příjem dat, detekci anomálií a diagnostiku , aniž by bylo nutné znát strojové učení. Poradce pro metriky můžete použít k:

  • Analýza multidimenzionálních dat z více zdrojů dat
  • Identifikace a korelace anomálií
  • Konfigurace a vyladění modelu detekce anomálií, který se používá u vašich dat
  • Diagnostika anomálií a pomoc s analýzou původní příčiny

Klíčové odkazy:

Začínáme

Aktuálně podporovaná prostředí

  • LtS verze Node.js
  • Nejnovější verze prohlížečů Safari, Chrome, Edge a Firefox.

Další podrobnosti najdete v našich zásadách podpory .

Požadavky

Pokud používáte Azure CLI, nahraďte <your-resource-group-name> a <your-resource-name> vlastními jedinečnými názvy:

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

Nainstalujte balíček @azure/ai-metrics-advisor.

Nainstalujte klientskou knihovnu Azure Metrics Advisor pro JavaScript pomocí npmnástroje :

npm install @azure/ai-metrics-advisor

Vytvořit a ověřit MetricsAdvisorClient nebo MetricsAdvisorAdministrationClient

K vytvoření objektu klienta pro přístup k rozhraní API Metrics Advisor budete potřebovat endpoint prostředek Metrics Advisor a credential. Klienti Advisoru pro metriky používají k ověření přihlašovací údaje klíče Služby Metrics Advisor.

Koncový bod pro váš prostředek Metrics Advisor najdete na webu Azure Portal nebo pomocí fragmentu kódu Azure CLI níže:

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

Použití klíče předplatného a klíče rozhraní API

K ověření klienta budete potřebovat dva klíče:

  • Klíč předplatného k vašemu prostředku Metrics Advisoru. Najdete ho v části Klíče a koncový bod vašeho prostředku na webu Azure Portal.
  • Klíč rozhraní API pro vaši instanci Služby Metrics Advisor. Najdete ho na webovém portálu Pro metriky Advisor v části Klíče rozhraní API v levé navigační nabídce. Adresu URL webového portálu najdete na webu Azure Portal v části Přehled vašeho prostředku.

Pomocí webu Azure Portal přejděte k prostředku Metrics Advisoru a načtěte klíč předplatného nebo použijte následující fragment kódu Azure CLI :

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

Kromě toho budete také potřebovat klíč rozhraní API pro jednotlivé uživatele z webového portálu Metrics Advisor.

Jakmile budete mít dva klíče a koncový bod, můžete pomocí MetricsAdvisorKeyCredential třídy ověřit klienty následujícím způsobem:

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

Použití adresáře služeb Azure

Ve většině příkladů se používá autorizace pomocí klíče rozhraní API, ale klienta můžete ověřit také pomocí Azure Active Directory pomocí knihovny Azure Identity Library. Pokud chcete použít zprostředkovatele DefaultAzureCredential uvedeného níže nebo jiného zprostředkovatele přihlašovacích údajů poskytnutého se sadou Azure SDK, nainstalujte @azure/identity balíček :

npm install @azure/identity

Pokud chcete provést ověření pomocí instančního objektu, budete také muset zaregistrovat aplikaci AAD a udělit přístup službě Metrics Advisor tím, že k instančnímu objektu přiřadíte roli Uživatel služeb Cognitive Services (poznámka: jiné role, například Vlastník, neudělí potřebná oprávnění, ke spuštění příkladů a vzorového kódu bude stačit jenom uživatel služeb Cognitive Services).

Nastavte hodnoty ID klienta, ID tenanta a tajného klíče klienta aplikace AAD jako proměnné prostředí: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. Podporujeme také ověřování pomocí přihlašovacích údajů Azure Active Directoty. Jako proměnné prostředí budete potřebovat ID tenanta Azure, ID klienta Azure a tajný klíč klienta Azure.

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

Klíčové koncepty

MetricsAdvisorClient

MetricsAdvisorClient je primární dotazovací rozhraní pro vývojáře, kteří používají klientskou knihovnu Metrics Advisor. Poskytuje asynchronní metody pro přístup ke konkrétnímu použití služby Metrics Advisor, jako je výpis incidentů, retrivní původní příčiny incidentů, načítání původních dat časových řad a dat časových řad obohacených službou.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient je rozhraní zodpovědné za správu entit v prostředcích Advisoru pro metriky, jako je správa datových kanálů, konfigurace detekce anomálií nebo konfigurace upozornění na anomálie.

Datový kanál

Datový kanál je to, co Služba Metrics Advisor ingestuje z vašeho zdroje dat, jako je cosmos DB nebo SQL Server. Datový kanál obsahuje řádky:

  • Časová razítka
  • nula nebo více dimenzí
  • jednu nebo více měr

Metric

Metrika je kvantifikovatelná míra, která se používá k monitorování a vyhodnocení stavu konkrétního obchodního procesu. Může se jednat o kombinaci více hodnot časových řad rozdělených do dimenzí. Metrika stavu webu může například obsahovat dimenze pro počet uživatelů a trh en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration je vyžadován pro každou časovou řadu a určuje, zda je bod v časové řadě anomálií.

Incident anomálie &

Jakmile se konfigurace detekce použije na metriky, vygenerují se vždy, AnomalyIncidentkdyž má jakákoli řada v rámci této řady objekt DataPointAnomaly.

Výstrahy

Můžete nakonfigurovat, které anomálie by měly aktivovat AnomalyAlert. Můžete nastavit více výstrah s různými nastaveními. Můžete například vytvořit výstrahu pro anomálie s nižším dopadem na firmu a další výstrahu pro důležitější výstrahy.

Hák

Nástroj Metrics Advisor umožňuje vytvářet a odebírat upozornění v reálném čase. Tyto výstrahy se odesílají přes internet pomocí oznamovacího hooku.

Úplný seznam konceptů najdete na stránce dokumentace k glosáři pro metriky .

Příklady

Následující část obsahuje několik fragmentů kódu JavaScriptu, které ilustrují běžné vzory používané v klientských knihovnách Služby Metrics Advisor.

Přidání datového kanálu z ukázkového zdroje dat

Poradce pro metriky podporuje připojení různých typů zdrojů dat. Tady je ukázka příjmu dat z 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;
}

Kontrola stavu příjmu dat

Po zahájení příjmu dat můžeme zkontrolovat stav příjmu dat.

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

Konfigurace detekce anomálií

Potřebujeme konfiguraci detekce anomálií, abychom zjistili, jestli je bod v časové řadě anomálií. I když se výchozí konfigurace detekce automaticky použije na každou metriku, můžete vyladit režimy detekce používané u vašich dat vytvořením přizpůsobené konfigurace detekce anomálií.

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

Přidání hooků pro příjem upozornění na anomálie

K odběru upozornění v reálném čase používáme hooky. V tomto příkladu vytvoříme webhook pro službu Metrics Advisor, do které se upozornění POST publikuje.

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

Konfigurace upozornění

Pak nakonfigurujeme, za jakých podmínek se má výstraha aktivovat a které zvoláky se mají výstrahu odeslat.

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

Dotazování na výsledky detekce anomálií

Na upozornění a anomálie se můžeme dotazovat.

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

Poradce při potížích

protokolování

Povolení protokolování může pomoct odhalit užitečné informace o selháních. Pokud chcete zobrazit protokol požadavků a odpovědí HTTP, nastavte proměnnou AZURE_LOG_LEVEL prostředí na info. Případně je možné protokolování povolit za běhu voláním setLogLevel v :@azure/logger

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

setLogLevel("info");

Podrobnější pokyny k povolení protokolů najdete v dokumentaci k balíčkům @azure/protokolovacího nástroje.

Další kroky

Podrobné příklady použití této knihovny najdete v adresáři ukázek .

Přispívání

Pokud chcete přispívat do této knihovny, přečtěte si příručku pro přispívání , kde najdete další informace o sestavení a testování.
kód.

Imprese