Biblioteca cliente de Azure Metrics Advisor para .NET: versión 1.1.0

  • Artículo

Azure Cognitive Services Metrics Advisor es un servicio en la nube que usa el aprendizaje automático para supervisar y detectar anomalías en los datos de serie temporal. Incluye las siguientes funcionalidades:

  • Analizar datos multidimensionales de varios orígenes de datos.
  • Identificar y correlacionar anomalías.
  • Configure y ajuste 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.

Código | fuente Paquete (NuGet) | Documentación | de referencia de APIDocumentación | del producto Muestras

Introducción

Instalar el paquete

Instale la biblioteca cliente de Azure Metrics Advisor para .NET con NuGet:

dotnet add package Azure.AI.MetricsAdvisor

Prerrequisitos

Creación de un recurso de Metrics Advisor

Puede crear un recurso de Metrics Advisor mediante:

Opción 1: Azure Portal.

Opción 2: CLI de Azure.

A continuación se muestra un ejemplo de cómo puede crear un recurso de Metrics Advisor mediante la CLI:

# Create a new resource group to hold the Metrics Advisor resource.
# If using an existing resource group, skip this step.
az group create --name <your-resource-name> --location <location>

# Create the Metrics Advisor resource.
az cognitiveservices account create \
    --name <your-resource-name> \
    --resource-group <your-resource-group-name> \
    --kind MetricsAdvisor \
    --sku <sku> \
    --location <location>
    --yes

Para obtener más información sobre cómo crear el recurso o cómo obtener la información de ubicación y SKU, consulte aquí.

Autenticar el cliente

Para interactuar con el servicio Metrics Advisor, deberá crear una instancia de las MetricsAdvisorClient clases o MetricsAdvisorAdministrationClient . Necesitará un punto de conexión, una clave de suscripción y una clave de API para crear instancias de un objeto de cliente.

Obtención del punto de conexión y la clave de suscripción

Puede obtener el punto de conexión y la clave de suscripción de la información del recurso en Azure Portal.

Como alternativa, puede usar el fragmento de código de la CLI de Azure siguiente para obtener la clave de suscripción del recurso de Metrics Advisor.

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

Obtención de la clave de API

Puede obtener la clave de API en el portal web de Metrics Advisor. Se le pedirá que inicie sesión para la autenticación.

Una vez que haya iniciado sesión, rellene el nombre del recurso de Azure Active Directory, Suscripción y Metrics Advisor.

Crear un MetricsAdvisorClient o metricsAdvisorAdministrationClient

Una vez que tenga la suscripción y las claves de API, cree un MetricsAdvisorKeyCredential. Con el punto de conexión y la credencial de la clave puede crear MetricsAdvisorClient:

string endpoint = "<endpoint>";
string subscriptionKey = "<subscriptionKey>";
string apiKey = "<apiKey>";
var credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);
var client = new MetricsAdvisorClient(new Uri(endpoint), credential);

También puede crear MetricsAdvisorAdministrationClient para realizar operaciones de administración:

string endpoint = "<endpoint>";
string subscriptionKey = "<subscriptionKey>";
string apiKey = "<apiKey>";
var credential = new MetricsAdvisorKeyCredential(subscriptionKey, apiKey);
var adminClient = new MetricsAdvisorAdministrationClient(new Uri(endpoint), credential);

Creación de metricsAdvisorClient o MetricsAdvisorAdministrationClient con Azure Active Directory

MetricsAdvisorKeyCredential La autenticación se usa en los ejemplos de esta guía de introducción, pero también puede autenticarse 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 paquete Azure.Identity:

Install-Package Azure.Identity

También tendrá que registrar una nueva aplicación de AAD y conceder acceso a Metrics Advisor mediante la asignación del rol a la "Cognitive Services Metrics Advisor User" entidad de servicio. Es posible que quiera asignar el "Cognitive Services Metrics Advisor Administrator" rol en su lugar si se requieren privilegios de administrador.

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.

Una vez establecidas las variables de entorno, puede crear un MetricsAdvisorClient:

string endpoint = "<endpoint>";
var client = new MetricsAdvisorClient(new Uri(endpoint), new DefaultAzureCredential());

Como alternativa, también puede crear un MetricsAdvisorAdministrationClient para realizar operaciones de administración:

string endpoint = "<endpoint>";
var adminClient = new MetricsAdvisorAdministrationClient(new Uri(endpoint), new DefaultAzureCredential());

Conceptos clave

MetricsAdvisorClient

MetricsAdvisorClient es la interfaz de consulta principal para los desarrolladores que usan la biblioteca cliente de Metrics Advisor. Proporciona métodos sincrónicos y asincrónicos para acceder a un uso específico de Metrics Advisor, como enumerar incidentes, recuperar las causas principales de los incidentes y recuperar datos de series temporales.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient es la interfaz responsable de administrar entidades en el recurso de Metrics Advisor. Proporciona métodos sincrónicos y asincrónicos para tareas como crear y actualizar fuentes de distribución de datos, configuraciones de detección de anomalías y configuraciones de alertas de anomalías.

Fuente de distribución de datos

Un DataFeed objeto ingiere periódicamente tablas de datos agregados del origen de datos, como CosmosDB o sql Server, y hace que esté disponible para el servicio Metrics Advisor. Es el punto de entrada de datos y, por tanto, el primer agente necesario que se va a establecer antes de que se pueda realizar la detección de anomalías. Consulte el ejemplo Creación de una fuente de distribución de datos a partir de un origen de datos a continuación para obtener más información.

Métrica de fuente de distribución de datos

Una DataFeedMetric, o simplemente "métrica", es una medida cuantificable que se usa para supervisar un estado de evaluación del estado de un proceso empresarial específico. Podría ser el costo de un producto durante los meses, o incluso una medida diaria de la temperatura. El servicio supervisará cómo este valor varía con el tiempo en la búsqueda de cualquier comportamiento anómalo. Una fuente de distribución de datos puede ingerir varias métricas del mismo origen de datos.

Dimensión de fuente de distribución de datos

O DataFeedDimensionsimplemente "dimensión", es un valor categórico que caracteriza una métrica. Por ejemplo, si una métrica representa el costo de un producto, el tipo de producto (por ejemplo, zapatos, sombreros) y la ciudad en la que se mediron estos valores (por ejemplo, Nueva York, Tokio) podría usarse como dimensión. La combinación de varias dimensiones identifica una serie temporal univariante determinada.

Serie temporal

Una serie temporal es una secuencia de puntos de datos indexados cronológicamente. Estos puntos de datos describen la variación del valor de una métrica a lo largo del tiempo.

Dada una métrica, el servicio Metrics Advisor crea una serie para cada combinación posible de valores de dimensión , lo que significa que se pueden supervisar varias series temporales para la misma métrica.

Por ejemplo, supongamos que el origen de datos devuelve las siguientes columnas de datos:

City Category Coste Ingresos
Nueva York Zapatos 1045.00 1345.00
Nueva York Sombreros 670.00 502.00
Delhi Zapatos 991.00 1009.00
Delhi Sombreros 623.00 711.00

Los costos y los ingresos son las métricas que quiere que supervise el servicio, mientras que la ciudad y la categoría son las dimensiones que caracterizan esas métricas. Hay 4 combinaciones de dimensiones posibles en estos datos:

  • Ciudad = Nueva York, Categoría = Zapatos
  • Ciudad = Nueva York, Categoría = Hats
  • Ciudad = Delhi, Categoría = Zapatos
  • Ciudad = Delhi, Categoría = Hats

Para cada métrica, el servicio creará 4 series temporales para supervisar los datos, cada uno de los cuales representa una posible combinación de dimensiones. Cada vez que se produce una ingesta de orígenes de datos, estas series se actualizarán con un nuevo punto de datos, si están disponibles en los datos recién ingeridos.

Anomalía de punto de datos

Un DataPointAnomaly, o simplemente "anomalía", se produce cuando un punto de datos de una serie temporal se comporta inesperadamente. Puede ocurrir cuando un valor de punto de datos es demasiado alto o demasiado bajo, o cuando su valor cambia abruptamente entre puntos de cierre. Puede especificar las condiciones que debe cumplir un punto de datos para considerarse una anomalía con .AnomalyDetectionConfiguration Una vez que se produce la ingesta de datos, el servicio aplica todas las configuraciones existentes al conjunto de nuevos puntos en busca de anomalías. Consulte el ejemplo Creación de una configuración de detección de anomalías a continuación para obtener más información.

Incidente de anomalías

Cuando se detectan anomalías en varias series temporales dentro de una métrica en una marca de tiempo determinada, el servicio Metrics Advisor agrupa automáticamente las anomalías que comparten la misma causa principal en una AnomalyIncidento simplemente "incidente". Esto eliminará significativamente el esfuerzo de comprobar cada anomalía individual y encontrará rápidamente el factor de contribución más importante a un problema.

Alerta de anomalías

Una AnomalyAlert, o simplemente "alerta", se desencadena cuando una anomalía detectada cumple un criterio especificado. Por ejemplo, se podría desencadenar una alerta cada vez que se detecta una anomalía con gravedad alta. Puede especificar las condiciones que una anomalía debe cumplir para desencadenar una alerta con .AnomalyAlertConfiguration Una vez realizada la detección de anomalías en los puntos de datos recién ingeridos, el servicio aplica todas las configuraciones existentes a las nuevas anomalías y cada configuración activa una única alerta para el conjunto de puntos que cumplen los criterios especificados. Las configuraciones de alerta no se establecen de forma predeterminada, por lo que debe crear una para empezar a desencadenar alertas. Consulte el ejemplo Creación de una configuración de alerta de anomalías a continuación para obtener más información.

Enlace de notificación

Un NotificationHook, o simplemente "enlace", es un medio de suscribirse a las notificaciones de alerta . Puede pasar un enlace a y AnomalyAlertConfiguration empezar a recibir notificaciones para cada alerta que cree. Consulte el ejemplo Creación de un enlace para recibir alertas de anomalías a continuación para obtener más información.

Seguridad para subprocesos

Garantizamos que todos los métodos de instancia de cliente son seguros para subprocesos e independientes entre sí (instrucciones). Esto garantiza que la recomendación de reutilizar instancias de cliente siempre es segura, incluso entre subprocesos.

Conceptos adicionales

Opciones | de cliente Acceso a la respuesta | Control de errores | Diagnóstico | Burla | Duración del cliente

Ejemplos

En la sección siguiente se proporcionan varios fragmentos de código que ilustran patrones comunes que se usan en la API de .NET de Metrics Advisor. Los fragmentos de código siguientes usan llamadas de servicio asincrónicas, pero tenga en cuenta que el paquete Azure.AI.MetricsAdvisor admite API sincrónicas y asincrónicas.

Creación de una fuente de distribución de datos a partir de un origen de datos

Metrics Advisor admite varios tipos de orígenes de datos. En este ejemplo se ilustrará una instancia de DataFeed que extrae datos de un servidor de SQL Server.

string sqlServerConnectionString = "<connectionString>";
string sqlServerQuery = "<query>";

var dataFeed = new DataFeed();

dataFeed.Name = "<dataFeedName>";
dataFeed.DataSource = new SqlServerDataFeedSource(sqlServerConnectionString, sqlServerQuery);
dataFeed.Granularity = new DataFeedGranularity(DataFeedGranularityType.Daily);

dataFeed.Schema = new DataFeedSchema();
dataFeed.Schema.MetricColumns.Add(new DataFeedMetric("cost"));
dataFeed.Schema.MetricColumns.Add(new DataFeedMetric("revenue"));
dataFeed.Schema.DimensionColumns.Add(new DataFeedDimension("category"));
dataFeed.Schema.DimensionColumns.Add(new DataFeedDimension("city"));

dataFeed.IngestionSettings = new DataFeedIngestionSettings(DateTimeOffset.Parse("2020-01-01T00:00:00Z"));

Response<DataFeed> response = await adminClient.CreateDataFeedAsync(dataFeed);

DataFeed createdDataFeed = response.Value;

Console.WriteLine($"Data feed ID: {createdDataFeed.Id}");
Console.WriteLine($"Data feed status: {createdDataFeed.Status.Value}");
Console.WriteLine($"Data feed created time: {createdDataFeed.CreatedOn.Value}");

Console.WriteLine($"Data feed administrators:");
foreach (string admin in createdDataFeed.Administrators)
{
    Console.WriteLine($" - {admin}");
}

Console.WriteLine($"Metric IDs:");
foreach (DataFeedMetric metric in createdDataFeed.Schema.MetricColumns)
{
    Console.WriteLine($" - {metric.Name}: {metric.Id}");
}

Console.WriteLine($"Dimensions:");
foreach (DataFeedDimension dimension in createdDataFeed.Schema.DimensionColumns)
{
    Console.WriteLine($" - {dimension.Name}");
}

Otras alternativas de autenticación de orígenes de datos

Algunos orígenes de datos admiten varios tipos de autenticación. Por ejemplo, un SqlServerDataFeedSource admite la cadena de conexión, la entidad de servicio y la identidad administrada. Puede comprobar la lista completa de orígenes de datos y sus tipos de autenticación aquí.

Una vez que haya asegurado que el origen de datos admite la autenticación que desea usar, debe establecer la Authentication propiedad al crear o actualizar el origen de datos:

var dataSoure = new SqlServerDataFeedSource("<connection-string>", "<query>")
{
    Authentication = SqlServerDataFeedSource.AuthenticationType.ManagedIdentity
};

Tenga en cuenta que, excepto los Basic tipos y ManagedIdentity de autenticación, también debe tener el identificador de un correspondiente DataSourceCredentialEntity en el servicio. Para crear una entidad de credencial, debe hacer lo siguiente:

string credentialName = "<credentialName>";

var credentialEntity = new ServicePrincipalCredentialEntity(credentialName, "<clientId>", "<clientSecret>", "<tenantId>");

Response<DataSourceCredentialEntity> response = await adminClient.CreateDataSourceCredentialAsync(credentialEntity);

DataSourceCredentialEntity createdCredentialEntity = response.Value;

Console.WriteLine($"Credential entity ID: {createdCredentialEntity.Id}");

Una vez que tenga el identificador, agréguelo a la DataSourceCredentialId propiedad al configurar el origen de datos:

var dataSoure = new SqlServerDataFeedSource("<connection-string>", "<query>")
{
    Authentication = SqlServerDataFeedSource.AuthenticationType.ServicePrincipal,
    DataSourceCredentialId = "<credentialId>"
};

Comprobación del estado de ingesta de una fuente de distribución de datos

Compruebe el estado de ingesta de un objeto creado DataFeedanteriormente.

string dataFeedId = "<dataFeedId>";

var startsOn = DateTimeOffset.Parse("2020-01-01T00:00:00Z");
var endsOn = DateTimeOffset.Parse("2020-09-09T00:00:00Z");
var options = new GetDataFeedIngestionStatusesOptions(startsOn, endsOn)
{
    MaxPageSize = 5
};

Console.WriteLine("Ingestion statuses:");
Console.WriteLine();

int statusCount = 0;

await foreach (DataFeedIngestionStatus ingestionStatus in adminClient.GetDataFeedIngestionStatusesAsync(dataFeedId, options))
{
    Console.WriteLine($"Timestamp: {ingestionStatus.Timestamp}");
    Console.WriteLine($"Status: {ingestionStatus.Status}");
    Console.WriteLine($"Service message: {ingestionStatus.Message}");
    Console.WriteLine();

    // Print at most 5 statuses.
    if (++statusCount >= 5)
    {
        break;
    }
}

Creación de una configuración de detección de anomalías

Cree un AnomalyDetectionConfiguration para indicar al servicio qué puntos de datos deben considerarse anomalías.

string metricId = "<metricId>";
string configurationName = "<configurationName>";

var detectionConfiguration = new AnomalyDetectionConfiguration()
{
    MetricId = metricId,
    Name = configurationName,
    WholeSeriesDetectionConditions = new MetricWholeSeriesDetectionCondition()
};

var detectCondition = detectionConfiguration.WholeSeriesDetectionConditions;

var hardSuppress = new SuppressCondition(1, 100);
detectCondition.HardThresholdCondition = new HardThresholdCondition(AnomalyDetectorDirection.Down, hardSuppress)
{
    LowerBound = 5.0
};

var smartSuppress = new SuppressCondition(4, 50);
detectCondition.SmartDetectionCondition = new SmartDetectionCondition(10.0, AnomalyDetectorDirection.Up, smartSuppress);

detectCondition.ConditionOperator = DetectionConditionOperator.Or;

Response<AnomalyDetectionConfiguration> response = await adminClient.CreateDetectionConfigurationAsync(detectionConfiguration);

AnomalyDetectionConfiguration createdDetectionConfiguration = response.Value;

Console.WriteLine($"Anomaly detection configuration ID: {createdDetectionConfiguration.Id}");

Creación de un enlace para recibir alertas de anomalías

Metrics Advisor admite las EmailNotificationHook clases y WebNotificationHook como medio para suscribirse a las notificaciones de alerta . En este ejemplo ilustraremos cómo crear EmailNotificationHook. Tenga en cuenta que debe pasar el enlace a una configuración de alerta de anomalías para empezar a recibir notificaciones. Consulte el ejemplo Creación de una configuración de alerta de anomalías a continuación para obtener más información.

string hookName = "<hookName>";

var emailHook = new EmailNotificationHook(hookName);

emailHook.EmailsToAlert.Add("email1@sample.com");
emailHook.EmailsToAlert.Add("email2@sample.com");

Response<NotificationHook> response = await adminClient.CreateHookAsync(emailHook);

NotificationHook createdHook = response.Value;

Console.WriteLine($"Hook ID: {createdHook.Id}");

Creación de una configuración de alerta de anomalías

Cree AnomalyAlertConfiguration para indicar al servicio qué anomalías deben desencadenar alertas.

string hookId = "<hookId>";
string anomalyDetectionConfigurationId = "<anomalyDetectionConfigurationId>";
string configurationName = "<configurationName>";

AnomalyAlertConfiguration alertConfiguration = new AnomalyAlertConfiguration()
{
    Name = configurationName
};

alertConfiguration.IdsOfHooksToAlert.Add(hookId);

var scope = MetricAnomalyAlertScope.CreateScopeForWholeSeries();
var metricAlertConfiguration = new MetricAlertConfiguration(anomalyDetectionConfigurationId, scope);

alertConfiguration.MetricAlertConfigurations.Add(metricAlertConfiguration);

Response<AnomalyAlertConfiguration> response = await adminClient.CreateAlertConfigurationAsync(alertConfiguration);

AnomalyAlertConfiguration createdAlertConfiguration = response.Value;

Console.WriteLine($"Alert configuration ID: {createdAlertConfiguration.Id}");

Consulta de anomalías detectadas y alertas desencadenadas

Examine las alertas creadas por una configuración de alerta de anomalía determinada.

string anomalyAlertConfigurationId = "<anomalyAlertConfigurationId>";

var startsOn = DateTimeOffset.Parse("2020-01-01T00:00:00Z");
var endsOn = DateTimeOffset.UtcNow;
var options = new GetAlertsOptions(startsOn, endsOn, AlertQueryTimeMode.AnomalyDetectedOn)
{
    MaxPageSize = 5
};

int alertCount = 0;

await foreach (AnomalyAlert alert in client.GetAlertsAsync(anomalyAlertConfigurationId, options))
{
    Console.WriteLine($"Alert created at: {alert.CreatedOn}");
    Console.WriteLine($"Alert at timestamp: {alert.Timestamp}");
    Console.WriteLine($"Id: {alert.Id}");
    Console.WriteLine();

    // Print at most 5 alerts.
    if (++alertCount >= 5)
    {
        break;
    }
}

Una vez que conozca el identificador de una alerta, enumere las anomalías que ha desencadenado dicha alerta.

string alertConfigurationId = "<alertConfigurationId>";
string alertId = "<alertId>";

var options = new GetAnomaliesForAlertOptions() { MaxPageSize = 3 };

int anomalyCount = 0;

await foreach (DataPointAnomaly anomaly in client.GetAnomaliesForAlertAsync(alertConfigurationId, alertId, options))
{
    Console.WriteLine($"Anomaly detection configuration ID: {anomaly.DetectionConfigurationId}");
    Console.WriteLine($"Data feed ID: {anomaly.DataFeedId}");
    Console.WriteLine($"Metric ID: {anomaly.MetricId}");
    Console.WriteLine($"Anomaly value: {anomaly.Value}");

    if (anomaly.ExpectedValue.HasValue)
    {
        Console.WriteLine($"Anomaly expected value: {anomaly.ExpectedValue}");
    }

    Console.WriteLine($"Anomaly at timestamp: {anomaly.Timestamp}");
    Console.WriteLine($"Anomaly detected at: {anomaly.CreatedOn}");
    Console.WriteLine($"Status: {anomaly.Status}");
    Console.WriteLine($"Severity: {anomaly.Severity}");
    Console.WriteLine("Series key:");

    foreach (KeyValuePair<string, string> dimension in anomaly.SeriesKey)
    {
        Console.WriteLine($"  Dimension '{dimension.Key}': {dimension.Value}");
    }

    Console.WriteLine();

    // Print at most 3 anomalies.
    if (++anomalyCount >= 3)
    {
        break;
    }
}

Solución de problemas

General

Cuando interactúe con la biblioteca cliente de Cognitive Services Metrics Advisor mediante el SDK de .NET, los errores devueltos por el servicio producirán un RequestFailedException con el mismo código de estado HTTP devuelto por la solicitud de LA API REST .

Por ejemplo, si intenta obtener una fuente de distribución de datos del servicio con un identificador inexistente, se devuelve un 404 error que indica "No encontrado".

string dataFeedId = "00000000-0000-0000-0000-000000000000";

try
{
    Response<DataFeed> response = await adminClient.GetDataFeedAsync(dataFeedId);
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Tenga en cuenta que se registra información adicional, como el mensaje de error devuelto por el servicio.

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"code":"ERROR_INVALID_PARAMETER","message":"datafeedId is invalid."}

Headers:
X-Request-ID: REDACTED
x-envoy-upstream-service-time: REDACTED
apim-request-id: REDACTED
Strict-Transport-Security: REDACTED
X-Content-Type-Options: REDACTED
Date: Thu, 08 Oct 2020 09:04:31 GMT
Content-Length: 69
Content-Type: application/json; charset=utf-8

Configuración del registro de la consola

La manera más sencilla de ver los registros es habilitar el registro de la consola.

Para crear un agente de escucha de registro del SDK de Azure que genere mensajes en la consola, use el AzureEventSourceListener.CreateConsoleLogger método .

// Set up a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Para más información sobre otros mecanismos de registro, consulte Ejemplos de diagnóstico.

Pasos siguientes

Los ejemplos que muestran cómo usar la biblioteca de Cognitive Services Metrics Advisor están disponibles en este repositorio de GitHub. Se proporcionan ejemplos para cada área funcional principal:

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para obtener más información, visite cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.