你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
适用于 Python 的 Azure 指标顾问客户端库 - 版本 1.0.0
指标顾问是一个可缩放的实时时序监视、警报和根本原因分析平台。 使用指标顾问执行以下操作:
- 分析来自多个数据源的多维数据
- 识别并关联异常
- 配置并微调用于数据的异常情况检测模型
- 诊断异常情况,并帮助进行根本原因分析
源代码 | 包 (Pypi) | API 参考文档 | 产品文档 | 示例
入门
安装包
使用 pip 安装适用于 Python 的 Azure 指标顾问客户端库:
pip install azure-ai-metricsadvisor --pre
先决条件
- 使用此包需要 Python 2.7、3.6 或更高版本。
- 需要 Azure 订阅和 指标顾问 serivce 才能使用此包。
验证客户端
需要两个密钥才能对客户端进行身份验证:
- 指标顾问资源的订阅密钥。 可以在 Azure 门户中资源的“密钥和终结点”部分中找到此密钥。
- 指标顾问实例的 API 密钥。 可以在指标顾问的 Web 门户中左侧导航菜单上的“API 密钥”中找到此密钥。
可以使用 键创建新的 MetricsAdvisorClient
或 MetricsAdvisorAdministrationClient
。
import os
from azure.ai.metricsadvisor import (
MetricsAdvisorKeyCredential,
MetricsAdvisorClient,
MetricsAdvisorAdministrationClient,
)
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
client = MetricsAdvisorClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key))
admin_client = MetricsAdvisorAdministrationClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key))
关键概念
MetricsAdvisorClient
MetricsAdvisorClient
帮助:
- 列出事件
- 列出事件的根本原因
- 检索服务扩充的原始时序数据和时序数据。
- 列出警报
- 添加反馈以优化模型
MetricsAdvisorAdministrationClient
MetricsAdvisorAdministrationClient
允许你
- 管理数据馈送
- 管理异常情况检测配置
- 管理异常警报配置
- 管理挂钩
DataFeed
指标 DataFeed
顾问从数据源(例如 Cosmos DB 或 SQL Server)中引入的内容。 数据馈送包含以下行:
- 时间戳
- 零个或多个维度
- 一个或多个度量值
指标
DataFeedMetric
是用于监视和评估特定业务流程状态的可计量度量值。 它可以是划分为多个维度的多个时序值的组合。 例如,Web 运行状况指标可能包含用户数和 en-us 市场的维度 。
AnomalyDetectionConfiguration
AnomalyDetectionConfiguration
是每个时序所必需的,并确定时序中的某个点是否为异常。
异常 & 事件
将检测配置应用于指标后, AnomalyIncident
每当其中的任何序列具有 时 DataPointAnomaly
,都会生成 。
警报
可以配置应触发 的 AnomalyAlert
异常。 可以使用不同的设置设置多个警报。 例如,可以针对对业务影响较低的异常创建警报,为更重要的警报创建另一个警报。
通知挂钩
通过指标顾问,可以创建和订阅实时警报。 这些警报使用 或 WebNotificationHook
等EmailNotificationHook
通知挂钩通过 Internet 发送。
示例
从示例或数据源添加数据馈送
指标顾问支持连接不同类型的数据源。 下面是从 SQL Server 引入数据的示例。
import os
import datetime
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorAdministrationClient
from azure.ai.metricsadvisor.models import (
SqlServerDataFeedSource,
DataFeedSchema,
DataFeedMetric,
DataFeedDimension,
DataFeedRollupSettings,
DataFeedMissingDataPointFillSettings
)
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
sql_server_connection_string = os.getenv("SQL_SERVER_CONNECTION_STRING")
query = os.getenv("SQL_SERVER_QUERY")
client = MetricsAdvisorAdministrationClient(
service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
data_feed = client.create_data_feed(
name="My data feed",
source=SqlServerDataFeedSource(
connection_string=sql_server_connection_string,
query=query,
),
granularity="Daily",
schema=DataFeedSchema(
metrics=[
DataFeedMetric(name="cost", display_name="Cost"),
DataFeedMetric(name="revenue", display_name="Revenue")
],
dimensions=[
DataFeedDimension(name="category", display_name="Category"),
DataFeedDimension(name="city", display_name="City")
],
timestamp_column="Timestamp"
),
ingestion_settings=datetime.datetime(2019, 10, 1),
data_feed_description="cost/revenue data feed",
rollup_settings=DataFeedRollupSettings(
rollup_type="AutoRollup",
rollup_method="Sum",
rollup_identification_value="__CUSTOM_SUM__"
),
missing_data_point_fill_settings=DataFeedMissingDataPointFillSettings(
fill_type="SmartFilling"
),
access_mode="Private"
)
return data_feed
检查引入状态
开始数据引入后,我们可以检查引入状态。
import datetime
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorAdministrationClient
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
data_feed_id = os.getenv("DATA_FEED_ID")
client = MetricsAdvisorAdministrationClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
ingestion_status = client.list_data_feed_ingestion_status(
data_feed_id,
datetime.datetime(2020, 9, 20),
datetime.datetime(2020, 9, 25)
)
for status in ingestion_status:
print("Timestamp: {}".format(status.timestamp))
print("Status: {}".format(status.status))
print("Message: {}\n".format(status.message))
配置异常情况检测配置
虽然默认检测配置会自动应用于每个指标,但我们可以通过创建自定义异常情况检测配置来优化数据上使用的检测模式。
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorAdministrationClient
from azure.ai.metricsadvisor.models import (
ChangeThresholdCondition,
HardThresholdCondition,
SmartDetectionCondition,
SuppressCondition,
MetricDetectionCondition,
)
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
metric_id = os.getenv("METRIC_ID")
client = MetricsAdvisorAdministrationClient(
service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
change_threshold_condition = ChangeThresholdCondition(
anomaly_detector_direction="Both",
change_percentage=20,
shift_point=10,
within_range=True,
suppress_condition=SuppressCondition(
min_number=5,
min_ratio=2
)
)
hard_threshold_condition = HardThresholdCondition(
anomaly_detector_direction="Up",
upper_bound=100,
suppress_condition=SuppressCondition(
min_number=2,
min_ratio=2
)
)
smart_detection_condition = SmartDetectionCondition(
anomaly_detector_direction="Up",
sensitivity=10,
suppress_condition=SuppressCondition(
min_number=2,
min_ratio=2
)
)
detection_config = client.create_detection_configuration(
name="my_detection_config",
metric_id=metric_id,
description="anomaly detection config for metric",
whole_series_detection_condition=MetricDetectionCondition(
condition_operator="OR",
change_threshold_condition=change_threshold_condition,
hard_threshold_condition=hard_threshold_condition,
smart_detection_condition=smart_detection_condition
)
)
return detection_config
配置警报配置
然后,让我们配置在哪些条件下需要触发警报。
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorAdministrationClient
from azure.ai.metricsadvisor.models import (
MetricAlertConfiguration,
MetricAnomalyAlertScope,
TopNGroupScope,
MetricAnomalyAlertConditions,
SeverityCondition,
MetricBoundaryCondition,
MetricAnomalyAlertSnoozeCondition,
)
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
anomaly_detection_configuration_id = os.getenv("DETECTION_CONFIGURATION_ID")
hook_id = os.getenv("HOOK_ID")
client = MetricsAdvisorAdministrationClient(
service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
alert_config = client.create_alert_configuration(
name="my alert config",
description="alert config description",
cross_metrics_operator="AND",
metric_alert_configurations=[
MetricAlertConfiguration(
detection_configuration_id=anomaly_detection_configuration_id,
alert_scope=MetricAnomalyAlertScope(
scope_type="WholeSeries"
),
alert_conditions=MetricAnomalyAlertConditions(
severity_condition=SeverityCondition(
min_alert_severity="Low",
max_alert_severity="High"
)
)
),
MetricAlertConfiguration(
detection_configuration_id=anomaly_detection_configuration_id,
alert_scope=MetricAnomalyAlertScope(
scope_type="TopN",
top_n_group_in_scope=TopNGroupScope(
top=10,
period=5,
min_top_count=5
)
),
alert_conditions=MetricAnomalyAlertConditions(
metric_boundary_condition=MetricBoundaryCondition(
direction="Up",
upper=50
)
),
alert_snooze_condition=MetricAnomalyAlertSnoozeCondition(
auto_snooze=2,
snooze_scope="Metric",
only_for_successive=True
)
),
],
hook_ids=[hook_id]
)
return alert_config
查询异常情况检测结果
我们可以查询警报和异常。
import datetime
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorClient
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
alert_config_id = os.getenv("ALERT_CONFIG_ID")
alert_id = os.getenv("ALERT_ID")
client = MetricsAdvisorClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
results = client.list_alerts(
alert_configuration_id=alert_config_id,
start_time=datetime.datetime(2020, 1, 1),
end_time=datetime.datetime(2020, 9, 9),
time_mode="AnomalyTime",
)
for result in results:
print("Alert id: {}".format(result.id))
print("Create time: {}".format(result.created_time))
results = client.list_anomalies(
alert_configuration_id=alert_config_id,
alert_id=alert_id,
)
for result in results:
print("Create time: {}".format(result.created_time))
print("Severity: {}".format(result.severity))
print("Status: {}".format(result.status))
查询事件
我们可以查询事件以查找检测配置。
import datetime
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorClient
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
anomaly_detection_configuration_id = os.getenv("DETECTION_CONFIGURATION_ID")
client = MetricsAdvisorClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
results = client.list_incidents(
detection_configuration_id=anomaly_detection_configuration_id,
start_time=datetime.datetime(2020, 1, 1),
end_time=datetime.datetime(2020, 9, 9),
)
for result in results:
print("Metric id: {}".format(result.metric_id))
print("Incident ID: {}".format(result.id))
print("Severity: {}".format(result.severity))
print("Status: {}".format(result.status))
查询根本原因
我们还可以查询事件的根本原因
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorClient
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
anomaly_detection_configuration_id = os.getenv("DETECTION_CONFIGURATION_ID")
incident_id = os.getenv("INCIDENT_ID")
client = MetricsAdvisorClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
results = client.list_incident_root_causes(
detection_configuration_id=anomaly_detection_configuration_id,
incident_id=incident_id,
)
for result in results:
print("Score: {}".format(result.score))
print("Description: {}".format(result.description))
添加用于接收异常警报的挂钩
我们可以添加一些挂钩,以便在触发警报时,我们可以得到回叫。
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential, MetricsAdvisorAdministrationClient
from azure.ai.metricsadvisor.models import EmailNotificationHook
service_endpoint = os.getenv("ENDPOINT")
subscription_key = os.getenv("SUBSCRIPTION_KEY")
api_key = os.getenv("API_KEY")
client = MetricsAdvisorAdministrationClient(service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key))
hook = client.create_hook(
hook=EmailNotificationHook(
name="email hook",
description="my email hook",
emails_to_alert=["alertme@alertme.com"],
external_link="https://docs.microsoft.com/en-us/azure/cognitive-services/metrics-advisor/how-tos/alerts"
)
)
异步 API
此库包含 Python 3.6+ 上支持的完整异步 API。 若要使用它,必须先安装异步传输,例如 aiohttp。 有关详细信息,请参阅 azure-core 文档 。
from azure.ai.metricsadvisor import MetricsAdvisorKeyCredential
from azure.ai.metricsadvisor.aio import MetricsAdvisorClient, MetricsAdvisorAdministrationClient
client = MetricsAdvisorClient(
service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
admin_client = MetricsAdvisorAdministrationClient(
service_endpoint,
MetricsAdvisorKeyCredential(subscription_key, api_key)
)
疑难解答
常规
Azure 指标顾问客户端将引发 Azure Core 中定义的异常。
日志记录
此库使用标准 日志记录 库进行日志记录。
有关 HTTP 会话的基本信息 (URL、标头等) 记录在 INFO
级别。
可以使用关键字参数在客户端或每个操作logging_enable
上启用详细DEBUG
级别日志记录,包括请求/响应正文和未执行的标头。
请参阅此处的示例的完整 SDK 日志记录文档。
后续步骤
更多示例代码
有关详细信息,请参阅 示例自述文件。
贡献
本项目欢迎贡献和建议。 大多数贡献要求你同意贡献者许可协议 (CLA),并声明你有权(并且确实有权)授予我们使用你的贡献的权利。 有关详细信息,请访问 cla.microsoft.com。
此项目采用了 Microsoft 开放源代码行为准则。 有关详细信息,请参阅行为准则常见问题解答,或如果有任何其他问题或意见,请与 联系。
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈