Udostępnij za pośrednictwem

Biblioteka klienta usługi Azure Metrics Advisor dla języka JavaScript — wersja 1.0.0

  • Artykuł

Metrics Advisor to część usług Azure Cognitive Services, która używa sztucznej inteligencji do monitorowania danych i wykrywania anomalii w danych szeregów czasowych. Usługa automatyzuje proces stosowania modeli do danych i udostępnia zestaw internetowych obszarów roboczych interfejsów API na potrzeby pozyskiwania danych, wykrywania anomalii i diagnostyki — bez konieczności znajomości uczenia maszynowego. Użyj klasyfikatora metryk, aby:

  • Analizowanie danych wielowymiarowych z wielu źródeł danych
  • Identyfikowanie i korelowanie anomalii
  • Konfigurowanie i dostosowywanie modelu wykrywania anomalii używanego na danych
  • Diagnozowanie anomalii i pomoc w analizie głównej przyczyny.

Kluczowe linki:

Wprowadzenie

Obecnie obsługiwane środowiska

Aby uzyskać więcej informacji, zobacz nasze zasady pomocy technicznej .

Wymagania wstępne

Jeśli używasz interfejsu wiersza polecenia platformy Azure, zastąp <your-resource-group-name> ciąg i <your-resource-name> własnymi unikatowymi nazwami:

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

Instalowanie pakietu @azure/ai-metrics-advisor

Zainstaluj bibliotekę klienta usługi Azure Metrics Advisor dla języka JavaScript przy użyciu polecenia npm:

npm install @azure/ai-metrics-advisor

Tworzenie i uwierzytelnianie MetricsAdvisorClient lub MetricsAdvisorAdministrationClient

Aby utworzyć obiekt klienta w celu uzyskania dostępu do interfejsu API klasyfikatora metryk, musisz mieć endpoint zasób Usługi Metrics Advisor i .credential Klienci usługi Metrics Advisor używają poświadczeń klucza klasyfikatora metryk do uwierzytelniania.

Punkt końcowy zasobu Advisor metryk można znaleźć w witrynie Azure Portal lub przy użyciu poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure :

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

Używanie klucza subskrypcji i klucza interfejsu API

Do uwierzytelnienia klienta potrzebne będą dwa klucze:

  • Klucz subskrypcji do zasobu Usługi Metrics Advisor. Możesz to znaleźć w sekcji Klucze i punkt końcowy zasobu w witrynie Azure Portal.
  • Klucz interfejsu API dla wystąpienia klasyfikatora metryk. Można to znaleźć w portalu internetowym dla usługi Metrics Advisor w obszarze Klucze interfejsu API w menu nawigacji po lewej stronie. Adres URL portalu internetowego można znaleźć w sekcji Przegląd zasobu w witrynie Azure Portal.

Użyj witryny Azure Portal , aby przejść do zasobu Usługi Metrics Advisor i pobrać klucz subskrypcji lub użyć poniższego fragmentu kodu interfejsu wiersza polecenia platformy Azure :

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

Ponadto będziesz potrzebować klucza interfejsu API dla poszczególnych użytkowników z portalu internetowego Usługi Metrics Advisor.

Po utworzeniu dwóch kluczy i punktu końcowego możesz użyć MetricsAdvisorKeyCredential klasy do uwierzytelniania klientów w następujący sposób:

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

Korzystanie z usługi Azure Service Directory

Autoryzacja klucza interfejsu API jest używana w większości przykładów, ale można również uwierzytelnić klienta za pomocą usługi Azure Active Directory przy użyciu biblioteki tożsamości platformy Azure. Aby użyć dostawcy DefaultAzureCredential pokazanego poniżej lub innych dostawców poświadczeń dostarczonych z zestawem Azure SDK, zainstaluj @azure/identity pakiet:

npm install @azure/identity

Aby uwierzytelnić się przy użyciu jednostki usługi, należy również zarejestrować aplikację usługi AAD i udzielić dostępu do klasyfikatora metryk, przypisując rolę "Użytkownik usług Cognitive Services" do jednostki usługi (uwaga: inne role, takie jak "Właściciel", nie przyzna niezbędnych uprawnień, wystarczy tylko "Użytkownik usług Cognitive Services", aby uruchomić przykłady i przykładowy kod).

Ustaw wartości identyfikatora klienta, identyfikatora dzierżawy i klucza tajnego klienta aplikacji usługi AAD jako zmienne środowiskowe: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. Obsługujemy również uwierzytelnianie za pomocą poświadczeń usługi Azure Active Directoty. Identyfikator dzierżawy platformy Azure, identyfikator klienta platformy Azure i klucz tajny klienta platformy Azure będą potrzebne jako zmienne środowiskowe.

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

Kluczowe pojęcia

MetricsAdvisorClient

MetricsAdvisorClient jest podstawowym interfejsem zapytań dla deweloperów korzystającym z biblioteki klienta Metrics Advisor. Zapewnia asynchroniczne metody uzyskiwania dostępu do określonego użycia klasyfikatora metryk, takiego jak wyświetlanie listy zdarzeń, pobieranie oryginalnych danych szeregów czasowych i danych szeregów czasowych wzbogaconych przez usługę.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient jest interfejsem odpowiedzialnym za zarządzanie jednostkami w zasobach usługi Metrics Advisor, takimi jak zarządzanie źródłami danych, konfiguracje wykrywania anomalii, konfiguracje alertów anomalii.

Źródło danych

Źródło danych to źródło danych, które doradca metryk pozyska ze źródła danych, takie jak cosmos DB lub serwer SQL. Źródło danych zawiera wiersze:

  • Sygnatury czasowe
  • zero lub więcej wymiarów
  • co najmniej jedna miara

Metric

Metryka jest miarą kwantyfikalną, która służy do monitorowania i oceniania stanu określonego procesu biznesowego. Może to być kombinacja wielu wartości szeregów czasowych podzielonych na wymiary. Na przykład metryka kondycji sieci Web może zawierać wymiary liczby użytkowników i rynku en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration jest wymagany dla każdego szeregu czasowego i określa, czy punkt w szeregach czasowych jest anomalią.

Incydent & anomalii

Po zastosowaniu konfiguracji wykrywania do metryk metryki są generowane za każdym razem, AnomalyIncidentgdy każda seria w niej ma wartość DataPointAnomaly.

Alerty

Można skonfigurować, które anomalie powinny wyzwalać element AnomalyAlert. Można ustawić wiele alertów z różnymi ustawieniami. Możesz na przykład utworzyć alert dotyczący anomalii z niższym wpływem na działalność biznesową, a inny dla ważniejszych alertów.

Hak

Usługa Metrics Advisor umożliwia tworzenie i subskrybowanie alertów w czasie rzeczywistym. Te alerty są wysyłane przez Internet przy użyciu haka powiadomień.

Aby zapoznać się z kompleksową listą pojęć, zapoznaj się ze stroną słownika porad dotyczących metryk .

Przykłady

W poniższej sekcji przedstawiono kilka fragmentów kodu JavaScript ilustrujących typowe wzorce używane w bibliotekach klienta usługi Metrics Advisor.

Dodawanie źródła danych z przykładowego źródła danych

Usługa Metrics Advisor obsługuje łączenie różnych typów źródeł danych. Oto przykład pozyskiwania danych 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;
}

Sprawdzanie stanu pozyskiwania

Po rozpoczęciu pozyskiwania danych możemy sprawdzić stan pozyskiwania.

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

Konfigurowanie konfiguracji wykrywania anomalii

Potrzebujemy konfiguracji wykrywania anomalii, aby określić, czy punkt w szeregach czasowych jest anomalią. Podczas gdy domyślna konfiguracja wykrywania jest automatycznie stosowana do każdej metryki, można dostosować tryby wykrywania używane na danych, tworząc niestandardową konfigurację wykrywania anomalii.

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

Dodawanie punktów zaczepienia do odbierania alertów anomalii

Używamy punktów zaczepienia subskrybuj alerty w czasie rzeczywistym. W tym przykładzie utworzymy element webhook dla usługi Metrics Advisor w celu opublikowania alertu.

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

Konfigurowanie konfiguracji alertu

Następnie skonfigurujmy, w których warunkach musi zostać wyzwolony alert i które punkty zaczepienia wysyłają alert.

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

Wyniki wykrywania anomalii zapytań

Możemy wykonywać zapytania dotyczące alertów i anomalii.

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

Rozwiązywanie problemów

Rejestrowanie

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań HTTP i odpowiedzi, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Możesz też włączyć rejestrowanie w czasie wykonywania, wywołując polecenie w elemecie setLogLevel@azure/logger:

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

setLogLevel("info");

Aby uzyskać bardziej szczegółowe instrukcje dotyczące włączania dzienników, zapoznaj się z dokumentami dotyczącymi pakietu @azure/rejestratora.

Następne kroki

Zapoznaj się z katalogiem samples , aby uzyskać szczegółowe przykłady dotyczące sposobu korzystania z tej biblioteki.

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat sposobu kompilowania i testowania
kod.

Wrażenia