Compartir a través de

Biblioteca cliente de Azure Metrics Advisor para JavaScript: versión 1.0.0

  • Artículo

Metrics Advisor forma parte de Azure Cognitive Services que usa inteligencia artificial para realizar la supervisión de datos y la detección de anomalías en los datos de series temporales. El servicio automatiza el proceso de aplicación de modelos a los datos y proporciona un conjunto de áreas de trabajo basadas en Web de API para la ingesta de datos, la detección de anomalías y los diagnósticos, sin necesidad de conocer el aprendizaje automático. Use Metrics Advisor para:

  • Analizar los datos multidimensionales de varios orígenes de datos
  • Identificar y correlacionar las anomalías
  • Configurar y ajustar el modelo de detección de anomalías usado en los datos
  • Diagnosticar las anomalías y ayudar con el análisis de la causa principal.

Vínculos principales:

Introducción

Entornos admitidos actualmente

Para más información, consulte la directiva de compatibilidad.

Requisitos previos

Si usa la CLI de Azure, reemplace <your-resource-group-name> y <your-resource-name> por sus propios nombres únicos:

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

Instalar el paquete @azure/ai-metrics-advisor

Instale la biblioteca cliente de Azure Metrics Advisor para JavaScript con npm:

npm install @azure/ai-metrics-advisor

Crear y autenticar MetricsAdvisorClient o MetricsAdvisorAdministrationClient

Para crear un objeto de cliente para acceder a la API de Metrics Advisor, necesitará el endpoint del recurso de Metrics Advisor y un credential. Los clientes de Metrics Advisor usan una credencial de clave de Metrics Advisor para autenticarse.

Puede encontrar el punto de conexión del recurso de Metrics Advisor en Azure Portal o mediante el fragmento de código de la CLI de Azure siguiente:

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

Uso de la clave de suscripción y la clave de API

Necesitará dos claves para autenticar al cliente:

  • Clave de suscripción al recurso de Metrics Advisor. Puede encontrarlo en la sección Claves y punto de conexión del recurso en Azure Portal.
  • La clave de API para la instancia de Metrics Advisor. Puede encontrarla en el portal web de Metrics Advisor, en Claves de API en el menú de navegación izquierdo. La dirección URL del portal web se puede encontrar en la sección Información general del recurso en Azure Portal.

Use Azure Portal para ir al recurso de Metrics Advisor y recuperar una clave de suscripción, o bien use el fragmento de código de la CLI de Azure siguiente:

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

Además, también necesitará la clave de API por usuario desde el portal web de Metrics Advisor.

Una vez que tenga las dos claves y el punto de conexión, puede usar la MetricsAdvisorKeyCredential clase para autenticar los clientes de la siguiente manera:

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 de Azure Service Directory

La autorización de clave de API se usa en la mayoría de los ejemplos, pero también puede autenticar el cliente con Azure Active Directory mediante la biblioteca de identidades de Azure. Para usar el proveedor DefaultAzureCredential que se muestra a continuación u otros proveedores de credenciales proporcionados con el SDK de Azure, instale el @azure/identity paquete:

npm install @azure/identity

Para autenticarse mediante una entidad de servicio, también tendrá que registrar una aplicación de AAD y conceder acceso a Metrics Advisor mediante la asignación del rol "Usuario de Cognitive Services" a la entidad de servicio (nota: otros roles como "Propietario" no concederán los permisos necesarios, solo "Usuario de Cognitive Services" bastará para ejecutar los ejemplos y el código de ejemplo).

Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET. También se admite la autenticación mediante azure Active Directoty Credential. Necesitará el identificador de inquilino de Azure, el identificador de cliente de Azure y el secreto de cliente de Azure como variables de entorno.

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

Conceptos clave

MetricsAdvisorClient

MetricsAdvisorClient es la interfaz de consulta principal para los desarrolladores que usan la biblioteca cliente de Metrics Advisor. Proporciona métodos asincrónicos para acceder a un uso específico de Metrics Advisor, como enumerar incidentes, reintentar las causas principales de los incidentes, recuperar los datos de serie temporal originales y los datos de serie temporal enriquecidos por el servicio.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient es la interfaz responsable de administrar entidades en los recursos de Metrics Advisor, como administrar fuentes de distribución de datos, configuraciones de detección de anomalías, configuraciones de alertas de anomalías.

Fuente de distribución de datos

Una fuente de distribución de datos es lo que Metrics Advisor ingiere del origen de datos, como Cosmos DB o SQL Server. Una fuente de distribución de datos contiene filas de:

  • marcas de tiempo
  • ninguna o varias dimensiones
  • una o varias medidas

Métrica

Una métrica es una medida cuantificable que se usa para supervisar y evaluar el estado de un proceso empresarial específico. Puede ser una combinación de varios valores de serie temporal divididos en dimensiones. Por ejemplo, una métrica de mantenimiento de la Web podría contener dimensiones para recuento de usuarios y el mercado es-es.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration es necesario para cada serie temporal y determina si un punto de la serie temporal es una anomalía.

Incidente de anomalías &

Después de aplicar una configuración de detección a las métricas, AnomalyIncidentlos se generan cada vez que cualquier serie dentro de ella tiene .DataPointAnomaly

Alerta

Puede configurar qué anomalías deben desencadenar .AnomalyAlert Puede establecer varias alertas con distintas configuraciones. Por ejemplo, podría crear una alerta para detectar anomalías con un menor impacto empresarial y otra para alertas más importantes.

Enlace

Metrics Advisor le permite crear alertas en tiempo real y suscribirse a ellas. Estas alertas se envían a través de Internet mediante un enlace de notificación.

Consulte la página de documentación del glosario de asesoramiento de métricas para obtener una lista completa de conceptos.

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código de JavaScript que ilustran patrones comunes que se usan en las bibliotecas cliente de Metrics Advisor.

Adición de una fuente de distribución de datos desde un origen de datos de ejemplo

Metrics Advisor admite la conexión de distintos tipos de orígenes de datos. Este es un ejemplo para ingerir datos 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;
}

Comprobación del estado de la ingesta

Tras iniciar la ingesta de datos, podemos comprobar el estado de la misma.

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

Configuración de la detección de anomalías

Necesitamos una configuración de detección de anomalías para determinar si un punto de la serie temporal es una anomalía. Aunque se aplica automáticamente una configuración de detección predeterminada a cada métrica, se pueden ajustar los modos de detección que se utilizan en los datos. Para ello, es preciso crear una configuración de detección de anomalías.

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

Adición de enlaces para recibir alertas de anomalías

Usamos enlaces que se suscriben a alertas en tiempo real. En este ejemplo, se crea un webhook en la que el servicio Metrics Advisor puede publicar la 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);
}

Configuración de las alertas

A continuación, vamos a configurar en qué condiciones se debe desencadenar una alerta y qué enlaces enviar la 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 de la detección de anomalías de las consultas

Podemos consultar las alertas y anomalías.

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

Solución de problemas

Registro

La habilitación del registro puede ayudar a descubrir información útil sobre los errores. Para ver un registro de solicitudes y respuestas HTTP, establezca la variable de entorno AZURE_LOG_LEVEL en info. Como alternativa, el registro se puede habilitar en tiempo de ejecución llamando a setLogLevel en @azure/logger:

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

setLogLevel("info");

Para obtener instrucciones más detalladas sobre cómo habilitar los registros, consulte los documentos del paquete @azure/logger.

Pasos siguientes

Eche un vistazo al directorio de ejemplos para obtener ejemplos detallados sobre cómo usar esta biblioteca.

Contribuciones

Si desea contribuir a esta biblioteca, lea la guía de contribución para obtener más información sobre cómo compilar y probar.
el código.

Impresiones