Biblioteca de clientes do Assistente de Métricas do Azure para .NET – versão 1.1.0

  • Artigo

O Assistente de Métricas dos Serviços Cognitivos do Azure é um serviço de nuvem que usa o aprendizado de máquina para monitorar e detectar anomalias em dados de série temporal. Ele inclui os seguintes recursos:

  • Analisar dados multidimensionais de várias fontes de dados.
  • Identificar e correlacionar anomalias.
  • Configure e ajuste o modelo de detecção de anomalias usado em seus dados.
  • Diagnosticar anomalias e ajudar com a análise de causa raiz.

Código-fonte | Pacote (NuGet) | Documentação | de referência da APIDocumentação do produto | Amostras

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Assistente de Métricas do Azure para .NET com o NuGet:

dotnet add package Azure.AI.MetricsAdvisor

Pré-requisitos

Criar um recurso do Assistente de Métricas

Você pode criar um recurso do Assistente de Métricas usando:

Opção 1: Portal do Azure.

Opção 2: CLI do Azure.

Veja abaixo um exemplo de como você pode criar um recurso do Assistente de Métricas usando a 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 obter mais informações sobre como criar o recurso ou como obter as informações de localização e sku, consulte aqui.

Autenticar o cliente

Para interagir com o serviço assistente de métricas, você precisará criar uma instância das MetricsAdvisorClient classes ou MetricsAdvisorAdministrationClient . Você precisará de um ponto de extremidade, uma chave de assinatura e uma chave de API para instanciar um objeto cliente.

Obter o ponto de extremidade e a chave de assinatura

Você pode obter o ponto de extremidade e a chave de assinatura das informações do recurso no Portal do Azure.

Como alternativa, você pode usar o snippet da CLI do Azure abaixo para obter a chave de assinatura do recurso assistente de métricas.

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

Obter a chave de API

Você pode obter a chave de API no Portal da Web do Assistente de Métricas. Você será solicitado a fazer logon para autenticação.

Depois de conectado, preencha o nome do recurso Azure Active Directory, Assinatura e Assistente de Métricas.

Criar um MetricsAdvisorClient ou um MetricsAdvisorAdministrationClient

Depois de ter a assinatura e as chaves de API, crie um MetricsAdvisorKeyCredential. Com o ponto de extremidade e a credencial de chave, você pode criar um MetricsAdvisorClient:

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

Você também pode criar um MetricsAdvisorAdministrationClient para executar operações de administração:

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

Criar um MetricsAdvisorClient ou um MetricsAdvisorAdministrationClient com o Azure Active Directory

MetricsAdvisorKeyCredential A autenticação é usada nos exemplos neste guia de introdução, mas você também pode autenticar 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:

Install-Package Azure.Identity

Você também precisará registrar um novo aplicativo do AAD e conceder acesso ao Assistente de Métricas atribuindo a "Cognitive Services Metrics Advisor User" função à sua entidade de serviço. Talvez você queira atribuir a "Cognitive Services Metrics Advisor Administrator" função se forem necessários privilégios de administrador.

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.

Depois de definir as variáveis de ambiente, você poderá criar um MetricsAdvisorClient:

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

Como alternativa, você também pode criar um MetricsAdvisorAdministrationClient para executar operações de administração:

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

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorClient é a principal interface de consulta para desenvolvedores usando a biblioteca de clientes do Assistente de Métricas. Ele fornece métodos síncronos e assíncronos para acessar um uso específico do Assistente de Métricas, como listar incidentes, recuperar causas raiz de incidentes e recuperar dados de série temporal.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient é a interface responsável por gerenciar entidades no recurso do Assistente de Métricas. Ele fornece métodos síncronos e assíncronos para tarefas como criar e atualizar feeds de dados, configurações de detecção de anomalias e configurações de alerta de anomalias.

Feed de Dados

Um DataFeed ingere periodicamente tabelas de dados agregados de sua fonte de dados, como o CosmosDB ou um SQL Server, e os disponibiliza para o serviço assistente de métricas. É o ponto de entrada dos dados e, portanto, o primeiro agente necessário a ser definido antes que a detecção de anomalias possa ocorrer. Consulte o exemplo Criar um feed de dados de uma fonte de dados abaixo para obter mais informações.

Métrica do Feed de Dados

Uma DataFeedMetric, ou simplesmente "métrica", é uma medida quantificável usada para monitorar uma avaliação do status de um processo comercial específico. Pode ser o custo de um produto ao longo dos meses, ou até mesmo uma medida diária de temperatura. O serviço monitorará como esse valor varia ao longo do tempo na pesquisa de qualquer comportamento anormal. Um feed de dados pode ingerir várias métricas da mesma fonte de dados.

Dimensão do Feed de Dados

Uma DataFeedDimensionou simplesmente "dimensão" é um valor categórico que caracteriza uma métrica. Por exemplo, se uma métrica representa o custo de um produto, o tipo de produto (por exemplo, sapatos, chapéus) e a cidade na qual esses valores foram medidos (por exemplo, Nova York, Tóquio) podem ser usados como uma dimensão. A combinação de várias dimensões identifica uma série temporal univariada específica.

Série temporal

Uma série temporal é uma sequência de pontos de dados indexados cronologicamente. Esses pontos de dados descrevem a variação do valor de uma métrica ao longo do tempo.

Dada uma métrica, o serviço Assistente de Métricas cria uma série para cada combinação possível de valores de dimensão , o que significa que várias séries temporais podem ser monitoradas para a mesma métrica.

Por exemplo, suponha que as seguintes colunas de dados sejam retornadas pela fonte de dados:

City Categoria Custo Receita
Nova Iorque Sapatos 1045.00 1345.00
Nova Iorque Chapéus 670.00 502.00
Deli Sapatos 991.00 1009.00
Deli Chapéus 623.00 711.00

Custo e receita são as métricas que você deseja que o serviço monitore, enquanto cidade e categoria são as dimensões que caracterizam essas métricas. Há 4 combinações de dimensões possíveis nestes dados:

  • Cidade = Nova York, Categoria = Sapatos
  • Cidade = Nova York, Categoria = Chapéus
  • Cidade = Delhi, Categoria = Sapatos
  • Cidade = Delhi, Categoria = Chapéus

Para cada métrica, o serviço criará quatro séries temporais para monitorar dados, cada uma representando uma possível combinação de dimensões. Sempre que ocorrer uma ingestão de fonte de dados, essas séries serão atualizadas com um novo ponto de dados, se disponíveis nos dados recém-ingeridos.

Anomalia do ponto de dados

Uma DataPointAnomalyou simplesmente "anomalia" ocorre quando um ponto de dados em uma série temporal se comporta inesperadamente. Pode ocorrer quando um valor de ponto de dados é muito alto ou muito baixo, ou quando seu valor é alterado abruptamente entre pontos próximos. Você pode especificar as condições que um ponto de dados deve atender para ser considerado uma anomalia com um AnomalyDetectionConfiguration. Após a ingestão de dados, o serviço aplica todas as configurações existentes ao conjunto de novos pontos na pesquisa de anomalias. Consulte o exemplo Criar uma configuração de detecção de anomalias abaixo para obter mais informações.

Incidente de anomalias

Quando houver anomalias detectadas em várias sériestemporais dentro de uma métrica em um determinado carimbo de data/hora, o serviço Assistente de Métricas agrupará automaticamente anomalias que compartilham a mesma causa raiz em um AnomalyIncidentou simplesmente "incidente". Isso removerá significativamente o esforço para marcar cada anomalia individual e localizará rapidamente o fator contribuinte mais importante para um problema.

Alerta de anomalias

Um AnomalyAlert, ou simplesmente "alerta", é disparado quando uma anomalia detectada atende a um critério especificado. Por exemplo, um alerta pode ser disparado sempre que uma anomalia com alta gravidade é detectada. Você pode especificar as condições que uma anomalia deve satisfazer para disparar um alerta com um AnomalyAlertConfiguration. Depois que a detecção de anomalias é executada em pontos de dados recém-ingeridos, o serviço aplica todas as configurações existentes às novas anomalias e cada configuração dispara um único alerta para o conjunto de pontos que satisfaz os critérios especificados. As configurações de alerta não são definidas por padrão, portanto, você precisa criar uma para começar a disparar alertas. Consulte o exemplo Criar uma configuração de alerta de anomalias abaixo para obter mais informações.

Gancho de notificação

Um NotificationHook, ou simplesmente "gancho", é um meio de assinar notificações de alerta . Você pode passar um gancho para um AnomalyAlertConfiguration e começar a receber notificações para cada alerta que ele cria. Consulte o exemplo Criar um gancho para receber alertas de anomalias abaixo para obter mais informações.

Acesso thread-safe

Garantimos que todos os métodos de instância do cliente sejam thread-safe e independentes uns dos outros (diretriz). Isso garante que a recomendação de reutilize instâncias de cliente seja sempre segura, mesmo entre threads.

Conceitos adicionais

Opções do | cliente Acessando a resposta | Tratamento de falhas | Diagnostics | Zombando | Tempo de vida do cliente

Exemplos

A seção a seguir fornece vários snippets de código ilustrando padrões comuns usados na API .NET do Assistente de Métricas. Os snippets abaixo usam chamadas de serviço assíncronas, mas observe que o pacote Azure.AI.MetricsAdvisor dá suporte a APIs síncronas e assíncronas.

Criar um feed de dados de uma fonte de dados

O Assistente de Métricas dá suporte a vários tipos de fontes de dados. Neste exemplo, ilustraremos como criar um DataFeed que extrai dados de um 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}");
}

Outras alternativas de autenticação da fonte de dados

Algumas fontes de dados dão suporte a vários tipos de autenticação. Por exemplo, um SqlServerDataFeedSource dá suporte à cadeia de conexão, à Entidade de Serviço e à identidade gerenciada. Você pode marcar a lista completa de fontes de dados e seus tipos de autenticação aqui.

Depois de certificar-se de que sua fonte de dados dá suporte à autenticação que deseja usar, você precisa definir a Authentication propriedade ao criar ou atualizar a fonte de dados:

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

Lembre-se de que, exceto para os Basic tipos e ManagedIdentity de autenticação, você também precisa ter a ID de um correspondente DataSourceCredentialEntity no serviço. Para criar uma entidade de credencial, você precisa fazer:

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

Depois de ter a ID, adicione-a DataSourceCredentialId à propriedade ao configurar sua fonte de dados:

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

Verificar o status de ingestão de um feed de dados

Verifique a status de ingestão de um criado 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;
    }
}

Criar uma configuração de detecção de anomalias

Crie um AnomalyDetectionConfiguration para informar ao serviço quais pontos de dados devem ser considerados anomalias.

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

Criar um gancho para receber alertas de anomalias

O Assistente de Métricas dá suporte às EmailNotificationHookWebNotificationHook classes e como meio de assinar notificações de alerta . Neste exemplo, ilustraremos como criar um EmailNotificationHook. Observe que você precisa passar o gancho para uma configuração de alerta de anomalias para começar a receber notificações. Consulte o exemplo Criar uma configuração de alerta de anomalias abaixo para obter mais informações.

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

Criar uma configuração de alerta de anomalias

Crie uma AnomalyAlertConfiguration para informar ao serviço quais anomalias devem disparar 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}");

Consultar anomalias detectadas e alertas disparados

Examine os alertas criados por uma determinada configuração de alerta de anomalia.

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

Depois de saber qual é a ID de um alerta, liste as anomalias que dispararam esse 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;
    }
}

Solução de problemas

Geral

Quando você interage com a biblioteca de clientes do Assistente de Métricas dos Serviços Cognitivos usando o SDK do .NET, os erros retornados pelo serviço resultarão em um RequestFailedException com o mesmo código http status retornado pela solicitação da API REST.

Por exemplo, se você tentar obter um feed de dados do serviço com uma ID inexistente, um 404 erro será retornado, indicando "Não Encontrado".

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

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

Observe que informações adicionais são registradas, como a mensagem de erro retornada pelo serviço.

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

Configuração do registro em log do console

A maneira mais simples de ver os logs é habilitar o log do console.

Para criar um ouvinte de log do SDK do Azure que gera mensagens para o console, use o AzureEventSourceListener.CreateConsoleLogger método .

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

Para saber mais sobre outros mecanismos de registro em log, confira Exemplos de diagnóstico.

Próximas etapas

Exemplos mostrando como usar a biblioteca do Assistente de Métricas dos Serviços Cognitivos estão disponíveis neste repositório GitHub. Exemplos são fornecidos para cada área funcional main:

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.