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

Artigo
04/05/2023

O Assistente de Métricas é parte integrante dos Serviços Cognitivos do Azure que usa a IA para realizar o monitoramento de dados e a detecção de anomalias em dados de série temporal. O serviço automatiza o processo de aplicação de modelos aos dados e fornece um conjunto de APIs de workspace baseado na Web para ingestão de dados, detecção de anomalias e diagnósticos, sem que você precise ter conhecimentos sobre o aprendizado de máquina. Use o Assistente de Métricas para:

Analisar dados multidimensionais de várias fontes de dados
Identificar e correlacionar anomalias
Configurar e ajustar o modelo de detecção de anomalias usado nos dados
Diagnosticar anomalias e ajudar com a análise de causa raiz.

Links principais:

Introdução

Ambientes com suporte no momento

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

Confira nossa política de suporte para mais detalhes.

Pré-requisitos

Uma assinatura do Azure.
Um recurso existente dos Serviços Cognitivos ou do Assistente de Métricas. Se você precisar criar o recurso, poderá usar o Portal do Azure ou a CLI do Azure.

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> por 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 clientes 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 cliente para acessar a API do Assistente de Métricas, você precisará do endpoint do recurso do Assistente de Métricas e de um credential. Os clientes do Assistente de Métricas usam uma credencial de chave do Assistente de Métricas para autenticar.

Você pode encontrar o ponto de extremidade para o recurso do Assistente de Métricas no Portal do Azure ou usando o snippet da CLI do Azure abaixo:

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

Usando chave de assinatura e chave de API

Você precisará de duas chaves para autenticar o cliente:

A chave de assinatura para o recurso do Assistente de Métricas. Você pode encontrá-lo na seção Chaves e Ponto de Extremidade do recurso no Portal do Azure.
A chave de API de sua instância do Assistente de Métricas. Encontre-a no portal da Web do Assistente de Métricas, em Chaves de API no menu de navegação à esquerda. A URL do portal da Web pode ser encontrada na seção Visão geral do recurso no Portal do Azure.

Use o Portal do Azure para navegar até o recurso do Assistente de Métricas e recuperar uma chave de assinatura ou usar o snippet da CLI do Azure abaixo:

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

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

Depois de ter as duas chaves e o ponto de extremidade, você pode usar a MetricsAdvisorKeyCredential classe para autenticar os clientes da seguinte maneira:

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

Usando o Diretório de Serviços do Azure

A autorização de chave de API é usada na maioria dos exemplos, mas você também pode autenticar o cliente com o Azure Active Directory usando a biblioteca de identidade do Azure. Para usar o provedor DefaultAzureCredential mostrado abaixo ou outros provedores de credenciais fornecidos com o SDK do Azure, instale o @azure/identity pacote:

npm install @azure/identity

Para autenticar usando uma entidade de serviço, você também precisará registrar um aplicativo do AAD e conceder acesso ao Assistente de Métricas atribuindo a função "Usuário dos Serviços Cognitivos" à entidade de serviço (observação: outras funções como "Proprietário" não concederão as permissões necessárias, apenas "Usuário dos Serviços Cognitivos" será suficiente para executar os exemplos e o código de exemplo).

Defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET. Também damos suporte à Autenticação pela Credencial do Azure Active Directoty. Você precisará da ID do Locatário do Azure, da ID do 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);

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorClient é a principal interface de consulta para desenvolvedores que usam a biblioteca de clientes do Assistente de Métricas. Ele fornece métodos assíncronos para acessar um uso específico do Assistente de Métricas, como listar incidentes, repetir as causas raiz de incidentes, recuperar dados de série temporal originais e dados de série temporal enriquecidos pelo serviço.

MetricsAdvisorAdministrationClient

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

Feed de Dados

Um feed de dados é o que o Assistente de Métricas ingere em sua fonte de dados, como o Cosmos DB ou um SQL Server. Um feed de dados contém linhas de:

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

Métrica

Uma métrica é uma medida quantificável usada para monitorar e avaliar o status 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 integridade da Web pode conter dimensões para contagem de usuários e 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 que uma configuração de detecção é aplicada às métricas, AnomalyIncidents são gerados sempre que qualquer série dentro dela tem um DataPointAnomaly.

Alerta

Você pode configurar quais anomalias devem disparar um AnomalyAlert. Você pode definir vários alertas com configurações diferentes. Por exemplo, você pode criar um alerta para anomalias com menor impacto nos negócios e outro para alertas mais importantes.

Gancho

O Assistente de Métricas permite criar e assinar alertas em tempo real. Esses alertas são enviados pela Internet usando um gancho de notificação.

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

Exemplos

A seção a seguir fornece vários snippets de código JavaScript ilustrando padrões comuns usados nas bibliotecas de clientes do Assistente de Métricas.

Adicionar um feed de dados de uma fonte de dados de exemplo
Verificar status de ingestão
Configurar a configuração de detecção de anomalias
Adicionar ganchos para receber alertas de anomalias
Configurar a configuração de alerta
consultaResultados da detecção de anomalias de consulta

Adicionar um feed de dados de uma fonte de dados de exemplo

O Assistente de Métricas dá suporte à conexão de diferentes tipos de fontes de dados. Este é um exemplo de ingestão de dados do 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 status da ingestão

Depois de iniciarmos a ingestão de dados, poderemos verificar o status 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}`);
  }
}

Definir a configuração da detecção de anomalias

Precisamos de uma configuração de detecção de anomalias para determinar se um ponto na série temporal é uma anomalia. Embora uma configuração de detecção padrão seja aplicada automaticamente a cada métrica, você poderá ajustar os modos de detecção usados nos seus dados criando uma configuração personalizada de detecção de anomalias.

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

Usamos ganchos para assinar alertas em tempo real. Neste exemplo, criaremos um webhook para o serviço Assistente de Métricas no qual o alerta será postado.

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

Definir a configuração de alerta

Em seguida, vamos configurar em quais condições um alerta precisa ser disparado e quais ganchos 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);
}

Consultar os resultados da detecção de anomalias

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

Solução de problemas

Registro em log

A habilitação do log pode ajudar a descobrir informações úteis sobre falhas. Para ver um log de solicitações e respostas HTTP, defina a variável de ambiente AZURE_LOG_LEVEL como info. Como alternativa, o log pode ser habilitado no runtime chamando setLogLevel em @azure/logger:

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

setLogLevel("info");

Para obter instruções mais detalhadas sobre como habilitar logs, veja os documentos do pacote @azure/logger.

Próximas etapas

Dê uma olhada no diretório de exemplos para obter exemplos detalhados sobre como usar essa biblioteca.

Participante

Se você quiser contribuir com essa 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

Compartilhar via

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

Introdução

Ambientes com suporte no momento

Pré-requisitos

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

Criar e autenticar `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`

Usando chave de assinatura e chave de API

Usando o Diretório de Serviços do Azure

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed de Dados

Métrica

AnomalyDetectionConfiguration

Incidente de & de anomalias

Alerta

Gancho

Exemplos

Adicionar um feed de dados de uma fonte de dados de exemplo

Verificar o status da ingestão

Definir a configuração da detecção de anomalias

Adicionar ganchos para receber alertas de anomalias

Definir a configuração de alerta

Consultar os resultados da detecção de anomalias

Solução de problemas

Registro em log

Próximas etapas

Participante

Recursos adicionais

Compartilhar via

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

Introdução

Ambientes com suporte no momento

Pré-requisitos

Instalar o pacote @azure/ai-metrics-advisor

Criar e autenticar MetricsAdvisorClient ou MetricsAdvisorAdministrationClient

Usando chave de assinatura e chave de API

Usando o Diretório de Serviços do Azure

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

Feed de Dados

Métrica

AnomalyDetectionConfiguration

Incidente de & de anomalias

Alerta

Gancho

Exemplos

Adicionar um feed de dados de uma fonte de dados de exemplo

Verificar o status da ingestão

Definir a configuração da detecção de anomalias

Adicionar ganchos para receber alertas de anomalias

Definir a configuração de alerta

Consultar os resultados da detecção de anomalias

Solução de problemas

Registro em log

Próximas etapas

Participante

Projetos relacionados

Recursos adicionais

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

Criar e autenticar `MetricsAdvisorClient` ou `MetricsAdvisorAdministrationClient`