Pustaka klien Azure Metrics Advisor untuk JavaScript - versi 1.0.0

Artikel
04/05/2023

Metrics Advisor adalah bagian dari Azure Cognitive Services yang menggunakan AI melakukan pemantauan data dan deteksi anomali dalam data rangkaian waktu. Layanan ini mengotomatiskan proses penerapan model ke data Anda, dan menyediakan sekumpulan ruang kerja berbasis web API untuk penyerapan data, deteksi anomali, dan diagnostik - tanpa perlu mengetahui pembelajaran mesin. Gunakan Azure Metrics Advisor untuk:

Menganalisis data multi-dimensi dari beberapa sumber data
Mengidentifikasi dan menghubungkan anomali
Mengonfigurasi dan menyempurnakan model deteksi anomali yang digunakan pada data Anda
Mendiagnosis anomali dan membantu analisis akar penyebab.

Tautan utama:

Memulai

Lingkungan yang didukung saat ini

Versi LTS dari Node.js
Safari, Chrome, Edge, dan Firefox versi terbaru.

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Langganan Azure.
Sumber daya Cognitive Services atau Metrics Advisor yang ada. Jika Anda perlu membuat sumber daya, Anda dapat menggunakan Portal Microsoft Azure atau Azure CLI.

Jika Anda menggunakan Azure CLI, ganti <your-resource-group-name> dan <your-resource-name> dengan nama unik Anda sendiri:

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

Pasang paket `@azure/ai-metrics-advisor`

Instal pustaka klien Azure Metrics Advisor untuk JavaScript dengan npm:

npm install @azure/ai-metrics-advisor

Membuat dan mengautentikasi `MetricsAdvisorClient` atau `MetricsAdvisorAdministrationClient`

Untuk membuat objek klien untuk mengakses API Metrics Advisor, Anda memerlukan endpoint sumber daya Metrics Advisor dan credential. Klien Metrics Advisor menggunakan kredensial kunci Metrics Advisor untuk mengautentikasi.

Anda dapat menemukan titik akhir untuk sumber daya Metrics Advisor Anda baik di Portal Microsoft Azure atau dengan menggunakan cuplikan Azure CLI di bawah ini:

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

Menggunakan Kunci Langganan dan Kunci API

Anda akan memerlukan dua kunci untuk mengautentikasi klien:

Kunci langganan ke sumber daya Metrics Advisor Anda. Anda dapat menemukan ini di bagian Kunci dan Titik Akhir sumber daya Anda di Portal Microsoft Azure.
Kunci API untuk instans Metrics Advisor Anda. Anda dapat menemukan ini di portal web untuk Metrics Advisor, di kunci API di menu navigasi kiri. Url portal web Anda dapat ditemukan di bagian Gambaran Umum sumber daya Anda di Portal Microsoft Azure.

Gunakan Portal Microsoft Azure untuk menelusuri sumber daya Metrics Advisor Anda dan mengambil kunci langganan, atau gunakan cuplikan Azure CLI di bawah ini:

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

Selain itu, Anda juga memerlukan kunci api per pengguna dari portal web Metrics Advisor Anda.

Setelah Anda memiliki dua kunci dan titik akhir, Anda dapat menggunakan MetricsAdvisorKeyCredential kelas untuk mengautentikasi klien sebagai berikut:

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

Menggunakan Azure Service Directory

Otorisasi kunci API digunakan di sebagian besar contoh, tetapi Anda juga dapat mengautentikasi klien dengan Azure Active Directory menggunakan pustaka Azure Identity. Untuk menggunakan penyedia DefaultAzureCredential yang ditunjukkan di bawah ini atau penyedia kredensial lain yang disediakan dengan Azure SDK, instal @azure/identity paket:

npm install @azure/identity

Untuk mengautentikasi menggunakan perwakilan layanan, Anda juga perlu mendaftarkan aplikasi AAD dan memberikan akses ke Metrics Advisor dengan menetapkan peran "Pengguna Cognitive Services" ke perwakilan layanan Anda (catatan: peran lain seperti "Pemilik" tidak akan memberikan izin yang diperlukan, hanya "Pengguna Cognitive Services" yang cukup untuk menjalankan contoh dan kode sampel).

Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. Kami juga mendukung Autentikasi oleh Kredensial Azure Active Directoty. Anda akan memerlukan ID Penyewa Azure, ID Klien Azure, dan Rahasia Klien Azure sebagai variabel lingkungan.

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

Konsep utama

MetricsAdvisorClient

MetricsAdvisorClient adalah antarmuka kueri utama untuk pengembang yang menggunakan pustaka klien Metrics Advisor. Ini menyediakan metode asinkron untuk mengakses penggunaan spesifik Metrics Advisor, seperti mencantumkan insiden, mengambil akar penyebab insiden, mengambil data rangkaian waktu asli dan data rangkaian waktu yang diperkaya oleh layanan.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient adalah antarmuka yang bertanggung jawab untuk mengelola entitas dalam sumber daya Metrics Advisor, seperti mengelola umpan data, konfigurasi deteksi anomali, konfigurasi peringatan anomali.

Umpan Data

Umpan data adalah yang diserap oleh Azure Metrics Advisor dari sumber data Anda, seperti Cosmos DB atau server SQL. Umpan data berisi baris:

tanda waktu
nol atau lebih dimensi
satu atau beberapa ukuran

Metrik

Metrik adalah ukuran terukur yang digunakan untuk memantau dan menilai status proses bisnis tertentu. Ini bisa berupa kombinasi dari beberapa nilai seri waktu yang dibagi menjadi dimensi. Misalnya metrik kesehatan web mungkin berisi dimensi untuk jumlah pengguna dan pasar en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration diperlukan untuk setiap rangkaian waktu, dan menentukan apakah titik dalam rangkaian waktu adalah anomali.

Insiden & Anomali

Setelah konfigurasi deteksi diterapkan ke metrik, AnomalyIncidents dihasilkan setiap kali seri apa pun di dalamnya memiliki DataPointAnomaly.

Peringatan

Anda dapat mengonfigurasi anomali mana yang harus memicu AnomalyAlert. Anda dapat mengatur beberapa pemberitahuan dengan pengaturan yang berbeda. Misalnya, Anda dapat membuat pemberitahuan untuk anomali dengan dampak bisnis yang lebih rendah, dan satu lagi untuk pemberitahuan yang lebih penting.

Kait

Azure Metrics Advisor memungkinkan Anda membuat dan berlangganan pemberitahuan real time. Pemberitahuan ini dikirim melalui internet, menggunakan hook pemberitahuan.

Silakan merujuk ke halaman dokumentasi Metrics Advisory Glossary untuk daftar konsep yang komprehensif.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode JavaScript yang mengilustrasikan pola umum yang digunakan dalam pustaka klien Metrics Advisor.

Menambahkan umpan data dari sumber data sampel
Periksa status penyerapan
Mengonfigurasi konfigurasi deteksi anomali
Menambahkan hook untuk menerima pemberitahuan anomali
Mengonfigurasi konfigurasi pemberitahuan
Hasil deteksi anomali kueri

Menambahkan umpan data dari sumber data sampel

Metrics Advisor mendukung penyambungan berbagai jenis sumber data. Berikut adalah sampel untuk menyerap data dari 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;
}

Memeriksa status penyerapan

Setelah mulai penyerapan data, kita dapat memeriksa status penyerapan.

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

Konfigurasikan konfigurasi deteksi anomali

Kita perlu konfigurasi deteksi anomali untuk menentukan apakah titik dalam seri waktu bersifat anomali. Meskipun konfigurasi deteksi default diterapkan secara otomatis ke setiap metrik, Anda dapat menyetel mode deteksi yang digunakan pada data Anda dengan membuat konfigurasi deteksi anomali yang dikustomisasi.

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

Menambahkan hook untuk menerima pemberitahuan anomali

Kami menggunakan kait berlangganan pemberitahuan real-time. Dalam contoh ini, kami membuat webhook untuk layanan Metrics Advisor tempat MEMPOSTING pemberitahuan.

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

Konfigurasikan konfigurasi peringatan

Kemudian mari kita konfigurasikan dalam kondisi mana pemberitahuan perlu dipicu dan kait mana yang akan mengirim pemberitahuan.

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

Hasil deteksi anomali kueri

Kita dapat mengkueri pemberitahuan dan anomali.

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

Pemecahan Masalah

Pencatatan

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/pencatat.

Langkah berikutnya

Silakan lihat direktori sampel untuk contoh terperinci tentang cara menggunakan pustaka ini.

Berkontribusi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membangun dan menguji
kode.

Microsoft Azure SDK untuk Javascript

Tayangan

Bagikan melalui

Pustaka klien Azure Metrics Advisor untuk JavaScript - versi 1.0.0

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Pasang paket `@azure/ai-metrics-advisor`

Membuat dan mengautentikasi `MetricsAdvisorClient` atau `MetricsAdvisorAdministrationClient`

Menggunakan Kunci Langganan dan Kunci API

Menggunakan Azure Service Directory

Konsep utama

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Umpan Data

Metrik

AnomalyDetectionConfiguration

Insiden & Anomali

Peringatan

Kait

Contoh

Menambahkan umpan data dari sumber data sampel

Memeriksa status penyerapan

Konfigurasikan konfigurasi deteksi anomali

Menambahkan hook untuk menerima pemberitahuan anomali

Konfigurasikan konfigurasi peringatan

Hasil deteksi anomali kueri

Pemecahan Masalah

Pencatatan

Langkah berikutnya

Berkontribusi

Saran dan Komentar

Sumber Daya Tambahan:

Bagikan melalui

Pustaka klien Azure Metrics Advisor untuk JavaScript - versi 1.0.0

Memulai

Lingkungan yang didukung saat ini

Prasyarat

Pasang paket @azure/ai-metrics-advisor

Membuat dan mengautentikasi MetricsAdvisorClient atau MetricsAdvisorAdministrationClient

Menggunakan Kunci Langganan dan Kunci API

Menggunakan Azure Service Directory

Konsep utama

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Umpan Data

Metrik

AnomalyDetectionConfiguration

Insiden & Anomali

Peringatan

Kait

Contoh

Menambahkan umpan data dari sumber data sampel

Memeriksa status penyerapan

Konfigurasikan konfigurasi deteksi anomali

Menambahkan hook untuk menerima pemberitahuan anomali

Konfigurasikan konfigurasi peringatan

Hasil deteksi anomali kueri

Pemecahan Masalah

Pencatatan

Langkah berikutnya

Berkontribusi

Proyek terkait

Saran dan Komentar

Sumber Daya Tambahan:

Pasang paket `@azure/ai-metrics-advisor`

Membuat dan mengautentikasi `MetricsAdvisorClient` atau `MetricsAdvisorAdministrationClient`