Azure.AI.MetricsAdvisor 1.1.0

Azure Metrics Advisor 的 .NET 客户端库

Azure 认知服务指标顾问是一种云服务，使用机器学习监视和检测时间序列数据中的异常。它包括以下功能

• 分析来自多个数据源的多维数据。
• 识别和关联异常。
• 配置和微调用于您的数据的异常检测模型。
• 诊断异常并帮助进行根本原因分析。

源代码 | 包（NuGet） | API 参考文档 | 产品文档 | 示例

入门

安装包

使用 NuGet 安装 Azure Metrics Advisor .NET 客户端库

dotnet add package Azure.AI.MetricsAdvisor

先决条件

• Azure 订阅。
• 现有的 Metrics Advisor 资源。

创建指标顾问资源

您可以使用以下方式创建指标顾问资源

选项 1: Azure 门户.

选项 2: Azure CLI.

以下是使用 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

有关创建资源的更多信息或获取位置和 SKU 信息如何，请参阅此处.

客户端认证

为了与指标顾问服务交互，您需要创建一个《a href="https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/MetricsAdvisorClient.cs" rel="noopener noreferrer nofollow">MetricsAdvisorClient

或将《a href="https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/metricsadvisor/Azure.AI.MetricsAdvisor/src/MetricsAdvisorAdministrationClient.cs" rel="noopener noreferrer nofollow">MetricsAdvisorAdministrationClient》类的实例。您需要一个《strong>端点》、《strong>订阅密钥》以及一个《strong>API 密钥》来创建一个客户端对象。

获取端点和订阅密钥

您可以从《a href="https://portal.azure.com/" rel="noopener noreferrer nofollow">Azure 门户的》资源信息中获取端点和订阅密钥。

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

获取 API 密钥

您可以从《a href="https://metricsadvisor.azurewebsites.net/" rel="noopener noreferrer nofollow">指标顾问 Web 门户中获取 API 密钥。您将登录进行身份验证。

登录后，填写您的 Azure Active Directory、订阅和指标顾问资源名称。

创建 MetricsAdvisorClient 或 MetricsAdvisorAdministrationClient

您创建一个MetricsAdvisorKeyCredential

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

有了端点和密钥凭证，您可以创建一个MetricsAdvisorClient

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

你还可以创建一个用于执行管理操作的 MetricsAdvisorAdministrationClient

本入门指南中的示例使用了MetricsAdvisorKeyCredential认证

您也可以使用Azure Identity 库通过 Azure Active Directory 进行认证。

Install-Package Azure.Identity

请安装 Azure.Identity 包

您还需要注册一个新的 AD 应用并授予 Metrics Advisor 访问权限

将 AD 应用的客户端 ID、租户 ID 和客户端密钥设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET。

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

设置环境变量后，您可以创建一个MetricsAdvisorClient

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

关键概念

MetricsAdvisorClient

MetricsAdvisorClient 是 Metrics Advisor 客户端库开发者主要的查询接口。它提供了同步和异步方法来访问 Metrics Advisor 的特定用途，例如列出事件、检索事件的根本原因以及检索时间序列数据。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient 是负责管理 Metrics Advisor 资源中实体的接口。它提供同步和异步方法用于创建和更新数据源、异常检测配置和异常警报配置等任务。

数据源

DataFeed 会定期从您的数据源（如 CosmosDB 或 SQL 服务器）中摄取聚合数据表，并为 Metrics Advisor 服务提供这些数据。它是数据的入口点，因此，在异常检测之前，必须首先设置一个入口点代理。有关更多信息，请参阅以下示例 从数据源创建数据源。

数据源度量

DataFeedMetric，或简称“度量”，是一种用于监控和评估特定业务流程状况的可量化测量。它可能是产品数月的成本，或甚至是温度的每日测量值。服务将监控此值随时间的变化，以寻找任何异常行为。一个 数据源 可以从相同的数据源摄入多个度量。

数据源维度

DataFeedDimension，或简称“维度”，是一种用于描述 度量 的分类值。例如，如果度量表示产品的成本，则可以使用产品类型（例如，鞋子、帽子）和测量的城市（例如，纽约、东京）作为维度。多个维度的组合可以识别特定的单一变量 时间序列。

时间序列

时间序列是一系列按时间顺序排列的数据点。这些数据点描述了一个 度量 随时间的变化。

给定一个度量，Metrics Advisor 服务为每个可能的 维度 值组合创建一个系列，这意味着可以对同一度量进行多时间序列的监控。

例如，假设您的数据源返回以下列的数据

城市	类别	成本	收入
纽约	鞋子	1045.00	1345.00
纽约	帽子	670.00	502.00
德里	鞋子	991.00	1009.00
德里	帽子	623.00	711.00

成本和收入是您希望服务监控的度量，而城市和类别是描述那些度量的维度。这些数据有 4 个可能的维度组合

• 城市 = 纽约，类别 = 鞋子
• 城市 = 纽约，类别 = 帽子
• 城市 =德里，类别 = 鞋子
• 城市 =德里，类别 = 帽子

对于每个度量，服务将创建 4 个时间序列来监控数据，每个序列代表一个可能的维度组合。每次数据源数据摄取发生时，这些序列将用新的数据点更新，如果在新摄入的数据中可用。

数据点异常

当 时间序列 中的数据点表现异常时，会发生 DataPointAnomaly，或简称“异常”。这可能发生在数据点值过高或过低，或者在相近的点之间值突然变化时。您可以使用 AnomalyDetectionConfiguration 指定数据点必须满足的条件才能被认为是异常。数据摄取发生后，服务将所有现有配置应用于新数据点集合以寻找异常。有关更多信息，请参阅以下示例 创建异常检测配置。

异常事件

当在特定时间戳下，一个度量指标中检测到多个异常时，Metrics Advisor 服务将自动将具有相同根本原因的异常组合成一个AnomalyIncident，或简单地称为“事件”。这将显著减少检查每个单个异常的努力，并快速找到导致问题最重要的贡献因素。

异常警报

当检测到的异常满足特定标准时，会触发一个AnomalyAlert，或简单地称为“警报”。例如，每当检测到严重程度高的异常时，都会触发警报。您可以使用AnomalyAlertConfiguration指定导致警报触发的异常必须满足的条件。在执行对新摄取的数据点的异常检测后，服务将所有现有配置应用于新的异常，并为满足指定标准的每个配置组合触发单个警报。默认情况下不设置警报配置，因此您需要创建一个以开始触发警报。有关更多信息，请参阅下方的示例创建异常警报配置。

通知钩子

NotificationHook，或简单地称为“钩子”，是订阅警报通知的一种方式。您可以将钩子传递给AnomalyAlertConfiguration，并开始接收它创建的每个警报的通知。有关更多信息，请参阅下方的示例创建接收异常警报的钩子。

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立（指南）。这确保了重用客户端实例的建议始终安全，即使在跨线程的情况下也是如此。

其他概念

客户端选项 | 访问响应 | 处理故障 | 诊断 | 模拟 | 客户端生命周期

示例

以下部分提供了几个代码片段，展示 Metrics Advisor .NET API 中常用的常见模式。下面的片段使用了异步服务调用，但请注意，Azure.AI.MetricsAdvisor 包同时支持同步和异步的 API。

• 从数据源创建数据馈送
• 其他数据源身份验证的替代方案
• 检查数据馈送的数据摄取状态
• 创建异常检测配置
• 创建接收异常警报的钩子
• 创建异常警报配置
• 查询检测到的异常和触发的警报

从数据源创建数据馈送

Metrics Advisor 支持多种类型的数据源。在本示例中，我们将展示如何创建从 SQL 服务器提取数据的 DataFeed。

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

其他数据源身份验证的替代方案

一些数据源支持多种类型的身份验证。例如，SqlServerDataFeedSource 支持连接字符串、服务主体和管理身份。您可以在此处查看数据源和它们的身份验证类型完整列表：此处。

一旦您确认了数据源支持您想要使用的身份验证方式，您在创建或更新数据源时需要设置 Authentication 属性。

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

请注意，除了Basic和ManagedIdentity类型的身份验证外，您还需要在服务中具有相应DataSourceCredentialEntity的ID。要创建凭证实体，您需要做

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

一旦有了ID，在设置数据源时，将其添加到DataSourceCredentialId属性

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

检查数据馈送的数据摄取状态

检查之前创建的DataFeed的摄取状态。

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

创建异常检测配置

创建一个AnomalyDetectionConfiguration来告诉服务哪些数据点应被视为异常。

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

创建接收异常警报的钩子

Metrics Advisor支持作为订阅警报通知的方式的EmailNotificationHook和WebNotificationHook类。在本示例中，我们将说明如何创建EmailNotificationHook。请注意，您需要将钩子传递给异常警报配置以启动接收通知。有关更多信息，请参阅下面的创建异常警报配置样本。

string hookName = "<hookName>";

var emailHook = new EmailNotificationHook(hookName);

emailHook.EmailsToAlert.Add("[email protected]");
emailHook.EmailsToAlert.Add("[email protected]");

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

NotificationHook createdHook = response.Value;

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

创建异常警报配置

创建一个AnomalyAlertConfiguration来告诉服务哪些异常应触发警报。

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

查询检测到的异常和触发的警报

查看给定异常警报配置创建的警报。

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

一旦知道了警报的ID，列出触发此警报的异常。

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

故障排除

一般

当您使用.NET SDK与认知服务指标顾问客户端库交互时，服务返回的错误将导致具有相同HTTP状态码的RequestFailedException，该HTTP状态码是由REST API请求返回的。

例如，如果您尝试使用不存在ID从服务中获取数据源，将返回404错误，表示“未找到”。

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

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

请注意，还会记录其他信息，例如服务返回的错误消息。

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

设置控制台日志记录

查看日志最简单的方法是启用控制台日志记录。

要创建一个输出消息到控制台的自定义Azure SDK日志监听器，请使用AzureEventSourceListener.CreateConsoleLogger方法。

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

要了解更多关于其他日志记录机制的信息，请参阅诊断样本。

下一步

此GitHub仓库中提供了说明如何使用认知服务指标顾问库的示例。为每个主要功能区域提供了示例。

• 数据源 CRUD 操作
• 凭证实体 CRUD 操作
• 数据源摄取操作
• 异常检测配置 CRUD 操作
• 钩子 CRUD 操作
• 异常警报配置 CRUD 操作
• 查询触发警报
• 查询检测到的异常
• 查询事件及其根本原因
• 查询时间序列信息
• 反馈 CRUD 操作

贡献

此项目欢迎.contributions和建议。大多数贡献都需要您同意一份贡献者许可协议（CLA），声明您有权利，并实际授予我们使用您的贡献的权利。有关详细信息，请访问cla.microsoft.com。

在您提交拉取请求时，CLA-bot将自动确定您是否需要提供CLA，并适当装饰PR（例如，标签，注释）。只需遵循机器人提供的说明即可。您将在使用我们的CLA的所有仓库中只需做一次。

本项目采用了微软开源行为准则。欲了解更多信息，请见行为准则常见问题或通过[email protected]联系，如有任何额外问题或评论。