JavaScript 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

[アーティクル]
04/05/2023

Metrics Advisor は、AI を使用してデータの監視と時系列データにおける異常検出を実行するサービスで、Azure Cognitive Services に含まれています。このサービスは、データにモデルを適用するプロセスを自動化すると共に、機械学習の知識を得なくてもデータインジェスト、異常検出、診断を行うことができる一連の API と Web ベースのワークスペースを備えています。 Metrics Advisor を使用すると、次のことができます。

複数のデータソースからの多次元データを分析する
異常を識別して関連付ける
実際のデータで使用される異常検出モデルを構成して微調整する
異常を診断し、根本原因分析に役立てる

主要リンク:

はじめに

現在サポートされている環境

Node.js の LTS バージョン
Safari、Chrome、Edge、Firefox の最新バージョン。

詳細については、Microsoft のサポートポリシーを参照してください。

前提条件

Azure サブスクリプション。
既存の Cognitive Services または Metrics Advisor リソース。リソースを作成する必要がある場合は、 Azure Portal または Azure CLI を使用できます。

Azure CLI を使用する場合は、と <your-resource-name> を独自の一意の名前に置き換えます<your-resource-group-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` パッケージのインストール

を使用して JavaScript 用 Azure Metrics Advisor クライアントライブラリを npmインストールします。

npm install @azure/ai-metrics-advisor

またはを作成して認証 `MetricsAdvisorClient` する `MetricsAdvisorAdministrationClient`

Metrics Advisor API にアクセスするためのクライアントオブジェクトを作成するには、Metrics Advisor リソースのと credentialが必要endpointです。 Metrics Advisor クライアントは、Metrics Advisor キーの資格情報を使用して認証します。

Metrics Advisor リソースのエンドポイントは、 Azure Portal または以下の Azure CLI スニペットを使用して確認できます。

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

サブスクリプションキーと API キーの使用

クライアントを認証するには、次の 2 つのキーが必要です。

Metrics Advisor リソースのサブスクリプションキー。これは、Azure Portal のリソースの [キーとエンドポイント] セクションにあります。
自分の Metrics Advisor インスタンスの API キー。これは Metrics Advisor の Web ポータルで確認できます (左側のナビゲーションメニューの [API キー] )。 Web ポータルの URL は、Azure Portal のリソースの [概要] セクションにあります。

Azure Portal を使用して Metrics Advisor リソースを参照し、サブスクリプションキーを取得するか、次の Azure CLI スニペットを使用します。

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

さらに、Metrics Advisor Web ポータルからユーザーごとの API キーも必要になります。

2 つのキーとエンドポイントを取得したら、クラスを 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 Service Directory の使用

API キーの承認はほとんどの例で使用されますが、Azure Id ライブラリを使用して Azure Active Directory でクライアントを認証することもできます。以下に示す DefaultAzureCredential プロバイダーまたは Azure SDK で提供されている他の資格情報プロバイダーを使用するには、パッケージを @azure/identity インストールしてください。

npm install @azure/identity

サービスプリンシパルを使用して認証するには、サービスプリンシパルに "Cognitive Services ユーザー" ロールを割り当てることで、AAD アプリケーションを登録し、Metrics Advisor へのアクセス権を付与する必要もあります (注: "所有者" などの他のロールは必要なアクセス許可を付与せず、例とサンプルコードを実行するには "Cognitive Services ユーザー" だけで十分です)。

AAD アプリケーションのクライアント ID、テナント ID、クライアントシークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET)。また、Azure Active Directoty 資格情報による認証もサポートしています。環境変数として、Azure テナント ID、Azure クライアント ID、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 は、Metrics Advisor クライアントライブラリを使用する開発者向けの主要なクエリインターフェイスです。これは、インシデントの一覧表示、インシデントの根本原因の確認、元の時系列データの取得、サービスによって強化された時系列データの取得など、Metrics Advisor の特定の用途にアクセスするための非同期メソッドを提供します。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient は、データフィードの管理、異常検出構成、異常アラート構成など、Metrics Advisor リソース内のエンティティの管理を担当するインターフェイスです。

データフィード

データフィードは、Cosmos DB や SQL server などのデータソースから Metrics Advisor が取り込むものです。データフィードには次の行が含まれます。

タイムスタンプ
0 個以上のディメンション
1 つ以上のメジャー

メトリック

メトリックは、特定のビジネスプロセスの状態を監視および評価するために使用される定量化可能なメジャーです。ディメンションに分割された複数の時系列値を組み合わせることができます。たとえば、web health のメトリックには、user count と en-us market のディメンションが含まれている場合があります。

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration は、時系列ごとに必要であり、時系列内のポイントが異常であるかどうかを判断します。

異常 & インシデント

メトリックに検出構成が適用されると、 AnomalyIncidentその中の任意の系列にが含 DataPointAnomalyまれるたびに s が生成されます。

アラート:

をトリガーする必要がある異常を AnomalyAlert構成できます。異なる設定で複数のアラートを設定できます。たとえば、ビジネスへの影響が小さい異常に対してはアラートを作成し、さらに重要なアラートについては別のアラートを作成できます。

フック

Metrics Advisor を使用すると、リアルタイムのアラートを作成し、サブスクライブすることができます。これらのアラートは、通知フックを使用してインターネット経由で送信されます。

概念の包括的な一覧については、メトリックアドバイザリ用語集のドキュメントページを参照してください。

例

次のセクションでは、Metrics Advisor クライアントライブラリで使用される一般的なパターンを示す JavaScript コードスニペットをいくつか示します。

サンプルデータソースからデータフィードを追加する
インジェストの状態を確認する
異常検出構成を構成する
異常アラートを受信するためのフックを追加する
アラート構成を構成する
異常検出結果のクエリを実行する

サンプルデータソースからデータフィードを追加する

Metrics Advisor では、さまざまな種類のデータソースの接続がサポートされています。ここでは、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 する Metrics Advisor サービスの Webhook を作成します。

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 に設定します。または、@azure/logger で setLogLevel を呼び出して、実行時にログ記録を有効にすることもできます。

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

setLogLevel("info");

ログを有効にする方法の詳細については、@azure/logger パッケージに関するドキュメントを参照してください。

次の手順

このライブラリの使用方法の詳細な例については、サンプルディレクトリを参照してください。

共同作成

このライブラリに投稿する場合は、投稿ガイドを参照して、ビルドとテストの方法の詳細を確認してください
コード。

Microsoft Azure SDK for Javascript

インプレッション数

次の方法で共有

JavaScript 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

はじめに

現在サポートされている環境

前提条件

`@azure/ai-metrics-advisor` パッケージのインストール

またはを作成して認証 `MetricsAdvisorClient` する `MetricsAdvisorAdministrationClient`

サブスクリプションキーと API キーの使用

Azure Service Directory の使用

主要な概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

データフィード

メトリック

AnomalyDetectionConfiguration

異常 & インシデント

アラート:

フック

例

サンプルデータソースからデータフィードを追加する

インジェストの状態を確認する

異常検出を構成する

異常アラートを受信するためのフックを追加する

アラートを構成する

異常検出の結果を照会する

トラブルシューティング

ログ記録

次の手順

共同作成

フィードバック

その他のリソース

次の方法で共有

JavaScript 用 Azure Metrics Advisor クライアント ライブラリ - バージョン 1.0.0

はじめに

現在サポートされている環境

前提条件

@azure/ai-metrics-advisor パッケージのインストール

または を作成して認証 MetricsAdvisorClient する MetricsAdvisorAdministrationClient

サブスクリプション キーと API キーの使用

Azure Service Directory の使用

主要な概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

データ フィード

メトリック

AnomalyDetectionConfiguration

異常 & インシデント

アラート:

フック

例

サンプル データ ソースからデータ フィードを追加する

インジェストの状態を確認する

異常検出を構成する

異常アラートを受信するためのフックを追加する

アラートを構成する

異常検出の結果を照会する

トラブルシューティング

ログ記録

次の手順

共同作成

関連プロジェクト

フィードバック

その他のリソース

JavaScript 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

`@azure/ai-metrics-advisor` パッケージのインストール

またはを作成して認証 `MetricsAdvisorClient` する `MetricsAdvisorAdministrationClient`

サブスクリプションキーと API キーの使用

データフィード

サンプルデータソースからデータフィードを追加する