JavaScript용 Azure Metrics Advisor 클라이언트 라이브러리 - 버전 1.0.0

Metrics Advisor는 Azure Cognitive Services의 일부로, AI를 사용하여 시계열 데이터에서 데이터 모니터링과 변칙 검색을 수행합니다. 이 서비스는 데이터에 모델을 적용하는 프로세스를 자동화하고, 데이터 수집, 변칙 검색 및 진단용 API 웹 기반 작업 영역 집합을 제공하므로 기계 학습을 몰라도 상관없습니다. Metrics Advisor를 사용하여 다음을 수행합니다.

• 여러 데이터 원본에서 다차원 데이터 분석
• 변칙 식별 및 상관 관계 지정
• 데이터에서 사용되는 변칙 검색 모델을 구성하고 미세 조정
• 변칙을 진단하고 근본 원인 분석 지원

주요 링크:

• 소스 코드
• 패키지(NPM)
• API 참조 설명서
• 제품 설명서
• 샘플

시작

현재 지원되는 환경

• Node.js의 LTS 버전
• 최신 버전의 Safari, Chrome, Edge, Firefox.

자세한 내용은 지원 정책을 참조하세요.

사전 요구 사항

• 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

또는 만들기 및 인증 MetricsAdvisorClientMetricsAdvisorAdministrationClient

Metrics Advisor API에 액세스하는 클라이언트 개체를 만들려면 Metrics Advisor 리소스 및 credential의 이 필요합니다endpoint. Metrics Advisor 클라이언트는 Metrics Advisor 키 자격 증명을 사용하여 인증합니다.

Azure Portal에서 또는 아래 AzureCLI 코드 조각을 사용하여 Metrics Advisor 리소스에 대한 엔드포인트를 찾을 수 있습니다.

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

구독 키 및 API 키 사용

클라이언트를 인증하려면 두 개의 키가 필요합니다.

• Metrics Advisor 리소스에 대한 구독 키입니다. Azure Portal에서 리소스의 키 및 엔드포인트 섹션에서 찾을 수 있습니다.
• Metrics Advisor 인스턴스에 대한 API 키입니다. 이는 Metrics Advisor용 웹 포털의 왼쪽 탐색 메뉴에 있는 API 키에서 찾을 수 있습니다. 웹 포털의 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 웹 포털의 사용자별 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 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 리소스의 엔터티를 관리하는 인터페이스입니다.

데이터 피드

데이터 피드는 Metrics Advisor가 Cosmos DB 또는 SQL Sever와 같은 데이터 원본에서 수집하는 대상입니다. 데이터 피드에는 다음과 같은 행이 포함됩니다.

• 타임스탬프
• 0개 이상의 차원
• 하나 이상의 측정값

메트릭

메트릭은 특정 비즈니스 프로세스의 상태를 모니터링하고 평가하는 데 사용되는 정량 측정값입니다. 차원으로 나눈 여러 개의 시계열 값의 조합일 수 있습니다. 예를 들어 웹 상태 메트릭은 사용자 수 및 en-us 시장의 차원을 포함할 수 있습니다.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration 는 모든 시계열에 필요하며 시계열의 점이 변칙인지 여부를 결정합니다.

변칙 & 인시던트

검색 구성이 메트릭 AnomalyIncident에 적용된 후 내의 모든 계열에 가 있을 때마다 s가 DataPointAnomaly생성됩니다.

경고

를 트리거해야 하는 변칙을 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 서비스에 대한 웹후크를 만듭니다.

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 package docs를 참조하세요.

다음 단계

이 라이브러리를 사용하는 방법에 대한 자세한 예제는 샘플 디렉터리를 참조하세요.

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 빌드 및 테스트 방법에 대해 자세히 알아보세요.
코드입니다.

관련된 프로젝트

• Javascript용 Microsoft Azure SDK