Клиентская библиотека Помощника по метрикам Azure для JavaScript версии 1.0.0

Статья
04/05/2023

Помощник по метрикам — это компонент Azure Cognitive Services, который использует искусственный интеллект для отслеживания данных и обнаружения аномалий во временных рядах. Эта служба автоматизирует процесс применения моделей к данным и предоставляет набор API и рабочую область на основе веб-интерфейсов для приема данных и обнаружения аномалий и диагностики без опыта работы с машинным обучением. Помощник по метрикам позволяет выполнять следующие действия:

анализ многомерных данных из нескольких источников данных;
выявление и сопоставление аномалий;
точная настройка модели обнаружения аномалий, используемой для ваших данных;
диагностика аномалий и помощь в анализе основных причин.

Основные ссылки:

Начало работы

Поддерживаемые в настоящее время среды

LTS версии Node.js
Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Предварительные требования

Подписка Azure.
Существующий ресурс Cognitive Services или помощника по метрикам. Если вам нужно создать ресурс, можно использовать портал Azure или Azure CLI.

Если вы используете Azure CLI, замените <your-resource-group-name> и <your-resource-name> собственными уникальными именами:

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

Установите пакет `@azure/ai-metrics-advisor`.

Установите клиентскую библиотеку Помощника по метрикам Azure для JavaScript с помощью npm:

npm install @azure/ai-metrics-advisor

Создание и проверка подлинности `MetricsAdvisorClient` или `MetricsAdvisorAdministrationClient`

Чтобы создать клиентский объект для доступа к API помощника по метрикам, вам потребуется endpoint ресурс помощника credentialпо метрикам и . Клиенты Помощника по метрикам используют учетные данные ключа помощника по метрикам для проверки подлинности.

Конечную точку для ресурса Помощника по метрикам можно найти на портале Azure или с помощью приведенного ниже фрагмента кода Azure CLI :

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

Использование ключа подписки и ключа API

Для проверки подлинности клиента потребуется два ключа:

Ключ подписки для ресурса Помощника по метрикам. Это можно найти в разделе Ключи и конечная точка ресурса на портале Azure.
Ключ API для экземпляра Помощника по метрикам. Его можно найти на веб-портале для Помощника по метрикам в разделе Ключи API в меню навигации слева. URL-адрес веб-портала можно найти в разделе Обзор ресурса на портале Azure.

Используйте портал Azure , чтобы перейти к ресурсу Помощника по метрикам и получить ключ подписки, или используйте приведенный ниже фрагмент кода Azure CLI :

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

Кроме того, вам также потребуется ключ API для каждого пользователя на веб-портале Помощника по метрикам.

Получив два ключа и конечную точку MetricsAdvisorKeyCredential , можно использовать класс для проверки подлинности клиентов следующим образом:

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

Использование каталога служб Azure

Авторизация ключа API используется в большинстве примеров, но вы также можете проверить подлинность клиента в Azure Active Directory с помощью библиотеки удостоверений Azure. Чтобы использовать поставщика DefaultAzureCredential, показанного ниже, или других поставщиков учетных данных, предоставляемых в пакете Azure SDK, установите @azure/identity пакет :

npm install @azure/identity

Чтобы пройти проверку подлинности с помощью субъекта-службы, необходимо также зарегистрировать приложение AAD и предоставить доступ к помощнику по метрикам, назначив субъекту-службе роль "Пользователь Cognitive Services" (примечание. Другие роли, такие как "Владелец", не предоставляют необходимых разрешений. Для запуска примеров и примера кода достаточно только "Пользователь Cognitive Services").

Задайте значения идентификатора клиента, идентификатора клиента и секрета клиента приложения AAD в качестве переменных среды: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. Мы также поддерживаем проверку подлинности с помощью учетных данных Azure Active Directoty. Вам потребуются идентификатор клиента Azure, идентификатор клиента Azure и секрет клиента 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);

Основные понятия

MetricsAdvisorClient

MetricsAdvisorClient — это основной интерфейс запросов для разработчиков, использующих клиентную библиотеку Помощника по метрикам. Он предоставляет асинхронные методы для доступа к определенному использованию помощника по метрикам, такие как перечисление инцидентов, устранение первопричин инцидентов, получение исходных данных временных рядов и данных временных рядов, обогащенных службой.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient — это интерфейс, отвечающий за управление сущностями в ресурсах помощника по метрикам, таких как управление веб-каналами данных, конфигурациями обнаружения аномалий, конфигурациями оповещений об аномалиях.

Веб-канал данных

Веб-канал данных — это то, какой из источников данных получает помощник по метрикам, например Cosmos DB или SQL Server. Веб-канал данных содержит строки:

отметки времени
– ноль или более измерений;
одна или несколько мер

Метрика

Метрика — это количественная мера, используемая для отслеживания и оценки состояния конкретного бизнес-процесса. Это может быть сочетание нескольких значений временных рядов, разделенных на измерения. Например, метрика работоспособности веб-сайта может содержать измерения для числа пользователей и рынка en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration является обязательным для каждого временного ряда и определяет, является ли точка во временных рядах аномалией.

Инцидент & аномалий

После применения конфигурации обнаружения к метрикам они создаются всякий раз, AnomalyIncidentкогда любой ряд в ней DataPointAnomalyимеет .

Предупреждение

Вы можете указать, какие аномалии должны активировать AnomalyAlert. Можно задать несколько предупреждений с разными параметрами. Например, можно создать оповещение об аномалиях с меньшим влиянием на бизнес, а другое — для более важных оповещений.

Обработчик

Помощник по метрикам позволяет создавать оповещения в режиме реального времени и подписываться на них. Эти оповещения отправляются через Интернет с помощью обработчика уведомлений.

Полный список концепций см. на странице документации по глоссариям рекомендаций по метрикам.

Примеры

В следующем разделе представлено несколько фрагментов кода JavaScript, иллюстрирующих распространенные шаблоны, используемые в клиентских библиотеках Помощника по метрикам.

Добавление веб-канала данных из примера источника данных
Проверка состояния приема
Настройка конфигурации обнаружения аномалий
Добавление перехватчиков для получения оповещений об аномалиях
Настройка конфигурации оповещений
Запрос результатов обнаружения аномалий

Добавление веб-канала данных из примера источника данных

Помощник по метрикам поддерживает подключение источников данных разных типов. Ниже приведен пример приема данных из 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;
}

Проверка состояния приема

После запуска приема данных мы можем проверить состояние приема.

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

Настройка конфигурации обнаружения аномалий

Нам требуется конфигурация обнаружения аномалий, чтобы определить, является ли точка данных во временных рядах аномалией. Хотя к каждой метрике автоматически применяется конфигурация обнаружения по умолчанию, вы можете отдельно настроить режимы обнаружения для своих данных, создав настраиваемую конфигурацию обнаружения аномалий.

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

Добавление перехватчиков для получения оповещений об аномалиях

Мы используем перехватчики, которые подписываются на оповещения в режиме реального времени. В этом примере мы создадим веб-перехватчик для службы "Помощник по метрикам", в который будут передаваться оповещения (с помощью POST).

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

Настройка конфигурации оповещения

Затем давайте настроим, в каких условиях необходимо активировать оповещение и какие обработчики для отправки оповещения.

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

Запрашивание результатов обнаружения аномалий

Мы можем запросить оповещения и аномалии.

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

Устранение неполадок

Ведение журнала

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. Кроме того, ведение журнала можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

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

setLogLevel("info");

Более подробные инструкции по включению журналов см. в документации по пакету @azure и средству ведения журнала.

Дальнейшие действия

Подробные примеры использования этой библиотеки см. в каталоге примеров .

Участие

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по участию , чтобы узнать больше о сборке и тестировании.
код.

Пакет SDK Microsoft Azure для JavaScript

Просмотры

Поделиться через

Клиентская библиотека Помощника по метрикам Azure для JavaScript версии 1.0.0

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Установите пакет `@azure/ai-metrics-advisor`.

Создание и проверка подлинности `MetricsAdvisorClient` или `MetricsAdvisorAdministrationClient`

Использование ключа подписки и ключа API

Использование каталога служб Azure

Основные понятия

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Веб-канал данных

Метрика

AnomalyDetectionConfiguration

Инцидент & аномалий

Предупреждение

Обработчик

Примеры

Добавление веб-канала данных из примера источника данных

Проверка состояния приема

Настройка конфигурации обнаружения аномалий

Добавление перехватчиков для получения оповещений об аномалиях

Настройка конфигурации оповещения

Запрашивание результатов обнаружения аномалий

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Дополнительные ресурсы

Поделиться через

Клиентская библиотека Помощника по метрикам Azure для JavaScript версии 1.0.0

Начало работы

Поддерживаемые в настоящее время среды

Предварительные требования

Установите пакет @azure/ai-metrics-advisor.

Создание и проверка подлинности MetricsAdvisorClient или MetricsAdvisorAdministrationClient

Использование ключа подписки и ключа API

Использование каталога служб Azure

Основные понятия

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Веб-канал данных

Метрика

AnomalyDetectionConfiguration

Инцидент & аномалий

Предупреждение

Обработчик

Примеры

Добавление веб-канала данных из примера источника данных

Проверка состояния приема

Настройка конфигурации обнаружения аномалий

Добавление перехватчиков для получения оповещений об аномалиях

Настройка конфигурации оповещения

Запрашивание результатов обнаружения аномалий

Устранение неполадок

Ведение журнала

Дальнейшие действия

Участие

Связанные проекты

Дополнительные ресурсы

Установите пакет `@azure/ai-metrics-advisor`.

Создание и проверка подлинности `MetricsAdvisorClient` или `MetricsAdvisorAdministrationClient`