Biblioteca de cliente do Assistente de Métricas do Azure para JavaScript – versão 1.0.0

Artigo
01/10/2024

O Assistente de Métricas faz parte dos Serviços Cognitivos do Azure que utiliza a IA efetua a monitorização de dados e a deteção de anomalias em dados de série temporal. O serviço automatiza o processo de aplicação de modelos aos seus dados e fornece um conjunto de áreas de trabalho baseadas na Web de APIs para ingestão de dados, deteção de anomalias e diagnósticos sem ter de conhecer a aprendizagem automática. Utilize o Assistente de Métricas para:

Analisar dados multidimensionais a partir de várias origens de dados
Identificar e correlacionar anomalias
Configurar e ajustar o modelo de deteção de anomalias utilizado nos seus dados
Diagnosticar anomalias e ajudar na análise da causa raiz.

Ligações principais:

Introdução

Ambientes atualmente suportados

Versões LTS do Node.js
Versões mais recentes do Safari, Chrome, Edge e Firefox.

Veja a nossa política de suporte para obter mais detalhes.

Pré-requisitos

Uma subscrição do Azure.
Um recurso do Assistente de Métricas ou Serviços Cognitivos existente. Se precisar de criar o recurso, pode utilizar o Portal do Azure ou a CLI do Azure.

Se utilizar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> pelos seus próprios nomes exclusivos:

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

Instalar o pacote `@azure/ai-metrics-advisor`

Instale a biblioteca de cliente do Assistente de Métricas do Azure para JavaScript com npm:

npm install @azure/ai-metrics-advisor

Criar e autenticar `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`

Para criar um objeto de cliente para aceder à API do Assistente de Métricas, precisará do endpoint recurso do Assistente de Métricas e de um credential. Os clientes do Assistente de Métricas utilizam uma credencial de chave do Assistente de Métricas para autenticar.

Pode encontrar o ponto final do recurso do Assistente de Métricas no Portal do Azure ou através do fragmento da CLI do Azure abaixo:

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

Utilizar a Chave de Subscrição e a Chave de API

Precisará de duas chaves para autenticar o cliente:

A chave de subscrição do recurso do Assistente de Métricas. Pode encontrá-lo na secção Chaves e Ponto Final do recurso no Portal do Azure.
A chave de API da instância do Assistente de Métricas. Pode encontrá-lo no portal Web do Assistente de Métricas, nas chaves de API no menu de navegação esquerdo. O URL do portal Web pode ser encontrado na secção Descrição geral do recurso no Portal do Azure.

Utilize o Portal do Azure para navegar para o recurso do Assistente de Métricas e obter uma chave de subscrição ou utilize o fragmento da CLI do Azure abaixo:

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

Além disso, também precisará da chave de API por utilizador do portal Web do Assistente de Métricas.

Assim que tiver as duas chaves e o ponto final, pode utilizar a MetricsAdvisorKeyCredential classe para autenticar os clientes da seguinte forma:

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

Utilizar o Azure Service Directory

A autorização da chave de API é utilizada na maioria dos exemplos, mas também pode autenticar o cliente com o Azure Active Directory com a biblioteca de Identidade do Azure. Para utilizar o fornecedor DefaultAzureCredential apresentado abaixo ou outros fornecedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Para autenticar com um principal de serviço, também terá de registar uma aplicação do AAD e conceder acesso ao Assistente de Métricas ao atribuir a função "Utilizador dos Serviços Cognitivos" ao principal de serviço (nota: outras funções como "Proprietário" não concederão as permissões necessárias, apenas "Utilizador dos Serviços Cognitivos" será suficiente para executar os exemplos e o código de exemplo).

Defina os valores do ID do cliente, do ID do inquilino e do segredo do cliente da aplicação do AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. Também suportamos a Autenticação pela Credencial do Azure Active Directoty. Precisará do ID do Inquilino do Azure, do ID de Cliente do Azure e do Segredo do Cliente do Azure como variáveis de 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);

Conceitos-chave

MetricsAdvisorClient

MetricsAdvisorClient é a interface de consulta principal para programadores que utilizam a biblioteca de cliente do Assistente de Métricas. Fornece métodos assíncronos para aceder a uma utilização específica do Assistente de Métricas, como a listagem de incidentes, a repetição de causas raiz de incidentes, a obtenção de dados de série temporal original e dados de série temporal enriquecidos pelo serviço.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient é a interface responsável pela gestão de entidades nos recursos do Assistente de Métricas, como a gestão de feeds de dados, configurações de deteção de anomalias, configurações de alerta de anomalias.

Feed de Dados

Um feed de dados é o que o Assistente de Métricas ingere a partir da sua origem de dados, como o Cosmos DB ou um servidor SQL. Um feed de dados contém linhas de:

carimbos de data/hora
zero ou mais dimensões
uma ou mais medidas

Metric

Uma métrica é uma medida quantificável que é utilizada para monitorizar e avaliar o estado de um processo empresarial específico. Pode ser uma combinação de vários valores de série temporal divididos em dimensões. Por exemplo, uma métrica de estado de funcionamento web pode conter dimensões para a contagem de utilizadores e para o mercado en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration é necessário para cada série temporal e determina se um ponto na série temporal é uma anomalia.

Incidente de & de Anomalias

Depois de uma configuração de deteção ser aplicada às métricas, AnomalyIncidents são gerados sempre que qualquer série dentro da mesma tiver um DataPointAnomaly.

Alerta

Pode configurar as anomalias que devem acionar um AnomalyAlert. Pode definir vários alertas com definições diferentes. Por exemplo, pode criar um alerta para anomalias com menor impacto comercial e outro para alertas mais importantes.

Gancho

O Assistente de Métricas permite-lhe criar e subscrever alertas em tempo real. Estes alertas são enviados através da Internet através de um gancho de notificação.

Veja a página documentação do Glossário de Aconselhamento de Métricas para obter uma lista abrangente de conceitos.

Exemplos

A secção seguinte fornece vários fragmentos de código JavaScript que ilustram padrões comuns utilizados nas bibliotecas de cliente do Assistente de Métricas.

Adicionar um feed de dados a partir de uma origem de dados de exemplo
Verificar o estado da ingestão
Configurar a configuração da deteção de anomalias
Adicionar ganchos para receber alertas de anomalias
Configurar a configuração de alertas
Resultados da deteção de anomalias de consulta

Adicionar um feed de dados a partir de uma origem de dados de exemplo

O Assistente de Métricas suporta a ligação de diferentes tipos de origens de dados. Eis um exemplo para ingerir dados de 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;
}

Verificar o estado da ingestão

Depois de iniciarmos a ingestão de dados, podemos verificar o estado da ingestão.

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

Configurar a configuração da deteção de anomalias

Precisamos de uma configuração de deteção de anomalias para determinar se um ponto na série temporal é uma anomalia. Embora uma configuração de deteção predefinida seja aplicada automaticamente a cada métrica, pode otimizar os modos de deteção utilizados nos seus dados ao criar uma configuração de deteção de anomalias personalizada.

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

Adicionar ganchos para receber alertas de anomalias

Utilizamos hooks para subscrever alertas em tempo real. Neste exemplo, vamos criar um webhook para o serviço Assistente de Métricas para publicar o alerta.

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

Configurar a configuração de alertas

Em seguida, vamos configurar as condições em que um alerta tem de ser acionado e quais os ganchos para enviar o alerta.

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

Resultados da deteção de anomalias de consulta

Podemos consultar os alertas e anomalias.

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

Resolução de problemas

Registo

Ativar o registo pode ajudar a descobrir informações úteis sobre falhas. Para ver um registo de pedidos e respostas HTTP, defina a variável de AZURE_LOG_LEVEL ambiente como info. Em alternativa, o registo pode ser ativado no runtime ao chamar setLogLevel no @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como ativar os registos, pode ver os documentos do pacote @azure/logger.

Passos seguintes

Veja o diretório de exemplos para obter exemplos detalhados sobre como utilizar esta biblioteca.

Contribuir

Se quiser contribuir para esta biblioteca, leia o guia de contribuição para saber mais sobre como criar e testar
o código.

SDK do Microsoft Azure para Javascript

Impressões

Partilhar via

Biblioteca de cliente do Assistente de Métricas do Azure para JavaScript – versão 1.0.0

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote `@azure/ai-metrics-advisor`

Criar e autenticar `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`

Utilizar a Chave de Subscrição e a Chave de API

Utilizar o Azure Service Directory

Conceitos-chave

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed de Dados

Metric

AnomalyDetectionConfiguration

Incidente de & de Anomalias

Alerta

Gancho

Exemplos

Adicionar um feed de dados a partir de uma origem de dados de exemplo

Verificar o estado da ingestão

Configurar a configuração da deteção de anomalias

Adicionar ganchos para receber alertas de anomalias

Configurar a configuração de alertas

Resultados da deteção de anomalias de consulta

Resolução de problemas

Registo

Passos seguintes

Contribuir

Recursos adicionais

Partilhar via

Biblioteca de cliente do Assistente de Métricas do Azure para JavaScript – versão 1.0.0

Introdução

Ambientes atualmente suportados

Pré-requisitos

Instalar o pacote @azure/ai-metrics-advisor

Criar e autenticar MetricsAdvisorClient ou MetricsAdvisorAdministrationClient

Utilizar a Chave de Subscrição e a Chave de API

Utilizar o Azure Service Directory

Conceitos-chave

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed de Dados

Metric

AnomalyDetectionConfiguration

Incidente de & de Anomalias

Alerta

Gancho

Exemplos

Adicionar um feed de dados a partir de uma origem de dados de exemplo

Verificar o estado da ingestão

Configurar a configuração da deteção de anomalias

Adicionar ganchos para receber alertas de anomalias

Configurar a configuração de alertas

Resultados da deteção de anomalias de consulta

Resolução de problemas

Registo

Passos seguintes

Contribuir

Projetos relacionados

Recursos adicionais

Instalar o pacote `@azure/ai-metrics-advisor`

Criar e autenticar `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`