Libreria client di Azure Metrics Advisor per JavaScript - versione 1.0.0

Articolo
04/05/2023

Advisor metriche è un componente di Servizi cognitivi di Azure che usa l'intelligenza artificiale per eseguire il monitoraggio dei dati e il rilevamento anomalie nei dati di serie temporali. Il servizio automatizza il processo di applicazione di modelli ai dati e fornisce un set di API e un'area di lavoro basata sul Web per l'inserimento dati, il rilevamento anomalie e la diagnostica, senza la necessità di conoscere i concetti di Machine Learning. Usare Advisor metriche per:

Analizzare dati multidimensionali da più origini dati
Identificare e correlare le anomalie
Configurare e ottimizzare il modello di rilevamento anomalie usato sui dati
Diagnosticare le anomalie e semplificare l'analisi della causa radice.

Collegamenti principali:

Introduzione

Ambienti attualmente supportati

Versioni LTS di Node.js
Ultime versioni di Safari, Chrome, Edge e Firefox.

Per altre informazioni, vedere i criteri di supporto.

Prerequisiti

Una sottoscrizione di Azure.
Una risorsa esistente di Servizi cognitivi o Advisor metriche. Se è necessario creare la risorsa, è possibile usare il portale di Azure o l'interfaccia della riga di comando di Azure.

Se si usa l'interfaccia della riga di comando di Azure, sostituire <your-resource-group-name> e <your-resource-name> con i propri nomi univoci:

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

Installare il pacchetto `@azure/ai-metrics-advisor`

Installare la libreria client di Azure Metrics Advisor per JavaScript con npm:

npm install @azure/ai-metrics-advisor

Creare e autenticare `MetricsAdvisorClient` o `MetricsAdvisorAdministrationClient`

Per creare un oggetto client per accedere all'API di Advisor metriche, è necessario disporre endpoint della risorsa di Advisor metriche e di un oggetto credential. I client di Advisor metriche usano le credenziali della chiave di Advisor metriche per l'autenticazione.

È possibile trovare l'endpoint per la risorsa di Advisor metriche nel portale di Azure o usando il frammento di interfaccia della riga di comando di Azure seguente:

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

Uso della chiave di sottoscrizione e della chiave API

Per autenticare il client sono necessarie due chiavi:

Chiave di sottoscrizione per la risorsa di Advisor metriche. È possibile trovarla nella sezione Chiavi ed endpoint della risorsa nel portale di Azure.
La chiave API dell'istanza di Advisor metriche. È possibile trovarla in Chiavi API nel menu di spostamento a sinistra del portale Web per Advisor metriche. L'URL del portale Web è disponibile nella sezione Panoramica della risorsa nel portale di Azure.

Usare il portale di Azure per passare alla risorsa di Advisor metriche e recuperare una chiave di sottoscrizione oppure usare il frammento di interfaccia della riga di comando di Azure seguente:

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

Inoltre, è necessaria anche la chiave API per utente dal portale Web di Advisor metriche.

Dopo aver ottenuto le due chiavi e l'endpoint, è possibile usare la MetricsAdvisorKeyCredential classe per autenticare i client nel modo seguente:

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

Uso della directory dei servizi di Azure

L'autorizzazione della chiave API viene usata nella maggior parte degli esempi, ma è anche possibile autenticare il client con Azure Active Directory usando la libreria di identità di Azure. Per usare il provider DefaultAzureCredential illustrato di seguito o altri provider di credenziali forniti con Azure SDK, installare il @azure/identity pacchetto:

npm install @azure/identity

Per eseguire l'autenticazione usando un'entità servizio, è anche necessario registrare un'applicazione AAD e concedere l'accesso a Advisor metriche assegnando il ruolo "Utente servizi cognitivi" all'entità servizio.Nota: altri ruoli come "Proprietario" non concedono le autorizzazioni necessarie, solo "Utente servizi cognitivi" sarà sufficiente per eseguire gli esempi e il codice di esempio.

Impostare i valori dell'ID client, dell'ID tenant e del segreto client dell'applicazione AAD come variabili di ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. È supportata anche l'autenticazione di Azure Active Directoty Credential. Sono necessari l'ID tenant di Azure, l'ID client di Azure e il segreto client di Azure come variabili di ambiente.

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

Concetti chiave

MetricsAdvisorClient

MetricsAdvisorClient è l'interfaccia di query principale per gli sviluppatori che usano la libreria client di Advisor metriche. Fornisce metodi asincroni per accedere a un uso specifico di Advisor metriche, ad esempio l'elenco di eventi imprevisti, la ripetizione delle cause radice degli eventi imprevisti, il recupero dei dati originali delle serie temporali e i dati delle serie temporali arricchiti dal servizio.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient è l'interfaccia responsabile della gestione delle entità nelle risorse di Advisor metriche, ad esempio la gestione dei feed di dati, le configurazioni di rilevamento anomalie, le configurazioni di avviso anomalie.

Feed di dati

Un feed di dati è ciò che Advisor metriche inserisce dall'origine dati, ad esempio Cosmos DB o un server SQL. Un feed di dati contiene righe di:

timestamp
zero o più dimensioni
una o più misure

Metrica

Una metrica è una misura quantificabile usata per monitorare e valutare lo stato di un processo aziendale specifico. Può essere una combinazione di più valori di serie temporali divisi in dimensioni. Una metrica di integrità Web può ad esempio contenere dimensioni relative al numero di utenti e al mercato statunitense.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration è obbligatorio per ogni serie temporale e determina se un punto della serie temporale è un'anomalia.

Evento imprevisto & anomalie

Dopo l'applicazione di una configurazione di rilevamento alle metriche, AnomalyIncidentgli oggetti vengono generati ogni volta che una serie all'interno ha un oggetto DataPointAnomaly.

Avviso

È possibile configurare le anomalie che devono attivare un oggetto AnomalyAlert. È possibile impostare più avvisi con impostazioni diverse. Ad esempio, è possibile creare un avviso per le anomalie con un impatto aziendale inferiore e un altro per avvisi più importanti.

Gancio

Advisor metriche consente di creare e sottoscrivere avvisi in tempo reale. Questi avvisi vengono inviati tramite Internet, usando un hook di notifica.

Per un elenco completo dei concetti, vedere la pagina della documentazione del glossario degli avvisi sulle metriche .

Esempio

La sezione seguente fornisce diversi frammenti di codice JavaScript che illustrano i modelli comuni usati nelle librerie client di Advisor metriche.

Aggiungere un feed di dati da un'origine dati di esempio
Controllare lo stato di inserimento
Configurare la configurazione del rilevamento anomalie
Aggiungere hook per la ricezione di avvisi di anomalie
Configurare la configurazione degli avvisi
Eseguire query sui risultati del rilevamento anomalie

Aggiungere un feed di dati da un'origine dati di esempio

Advisor metriche supporta la connessione di diversi tipi di origini dati. Ecco un esempio di inserimento dati da 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;
}

Controllare lo stato dell'inserimento

Dopo aver avviato l'inserimento dati, è possibile controllarne lo stato.

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

Configurare il rilevamento anomalie

Per determinare se un punto della serie temporale è un'anomalia, è necessaria una configurazione del rilevamento anomalie. Anche se a ogni metrica viene automaticamente applicata una configurazione di rilevamento predefinita, è possibile ottimizzare le modalità usate per i dati creando una configurazione di rilevamento anomalie personalizzata.

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

Aggiungere hook per la ricezione di avvisi di anomalie

Gli hook vengono usati per sottoscrivere gli avvisi in tempo reale. In questo esempio viene creato un webhook a cui il servizio Advisor metriche invia l'avviso tramite 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);
}

Configurare gli avvisi

Si configurerà quindi in quali condizioni deve essere attivato un avviso e quali hook inviare l'avviso.

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

Eseguire query sui risultati del rilevamento anomalie

È possibile eseguire query sugli avvisi e sulle anomalie.

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

Risoluzione dei problemi

Registrazione

L'abilitazione della registrazione consente di individuare informazioni utili sugli errori. Per visualizzare un log di richieste e risposte HTTP, impostare la variabile di ambiente AZURE_LOG_LEVEL su info. In alternativa, la registrazione può essere abilitata in fase di esecuzione chiamando setLogLevel in @azure/logger:

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

setLogLevel("info");

Per istruzioni più dettagliate su come abilitare i log, è possibile esaminare la documentazione del pacchetto di @azure/logger.

Passaggi successivi

Per esempi dettagliati su come usare questa libreria, vedere la directory degli esempi .

Contributo

Per contribuire a questa libreria, leggere la guida ai contributi per altre informazioni su come compilare e testare
il codice.

Microsoft Azure SDK per Javascript

Impression

Condividi tramite

Libreria client di Azure Metrics Advisor per JavaScript - versione 1.0.0

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto `@azure/ai-metrics-advisor`

Creare e autenticare `MetricsAdvisorClient` o `MetricsAdvisorAdministrationClient`

Uso della chiave di sottoscrizione e della chiave API

Uso della directory dei servizi di Azure

Concetti chiave

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed di dati

Metrica

AnomalyDetectionConfiguration

Evento imprevisto & anomalie

Avviso

Gancio

Esempio

Aggiungere un feed di dati da un'origine dati di esempio

Controllare lo stato dell'inserimento

Configurare il rilevamento anomalie

Aggiungere hook per la ricezione di avvisi di anomalie

Configurare gli avvisi

Eseguire query sui risultati del rilevamento anomalie

Risoluzione dei problemi

Registrazione

Passaggi successivi

Contributo

Risorse aggiuntive

Condividi tramite

Libreria client di Azure Metrics Advisor per JavaScript - versione 1.0.0

Introduzione

Ambienti attualmente supportati

Prerequisiti

Installare il pacchetto @azure/ai-metrics-advisor

Creare e autenticare MetricsAdvisorClient o MetricsAdvisorAdministrationClient

Uso della chiave di sottoscrizione e della chiave API

Uso della directory dei servizi di Azure

Concetti chiave

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed di dati

Metrica

AnomalyDetectionConfiguration

Evento imprevisto & anomalie

Avviso

Gancio

Esempio

Aggiungere un feed di dati da un'origine dati di esempio

Controllare lo stato dell'inserimento

Configurare il rilevamento anomalie

Aggiungere hook per la ricezione di avvisi di anomalie

Configurare gli avvisi

Eseguire query sui risultati del rilevamento anomalie

Risoluzione dei problemi

Registrazione

Passaggi successivi

Contributo

Progetti correlati

Risorse aggiuntive

Installare il pacchetto `@azure/ai-metrics-advisor`

Creare e autenticare `MetricsAdvisorClient` o `MetricsAdvisorAdministrationClient`