Python 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

[アーティクル]
04/05/2023

Metrics Advisor は、スケーラブルなリアルタイム時系列監視、アラート、根本原因分析プラットフォームです。 Metrics Advisor を使用すると、次のことができます。

複数のデータソースからの多次元データを分析する
異常を識別して関連付ける
実際のデータで使用される異常検出モデルを構成して微調整する
異常を診断し、根本原因分析に役立てる

ソースコード | パッケージ (Pypi) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

パッケージをインストールする

pip を使用して Python 用 Azure Metrics Advisor クライアントライブラリをインストールします。

pip install azure-ai-metricsadvisor --pre

前提条件

このパッケージを使用するには、Python 2.7 または3.6 以降が必要です。
このパッケージを使用するには、 Azure サブスクリプションと Metrics Advisor serivce が必要です。

クライアントを認証する

クライアントを認証するには、次の 2 つのキーが必要です。

Metrics Advisor リソースのサブスクリプションキー。これは、Azure portal 内の自分のリソースの [キーとエンドポイント] セクションで確認できます。
自分の Metrics Advisor インスタンスの API キー。これは Metrics Advisor の 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 サーバーなどのデータソースから Metrics Advisor が取り込むものです。データフィードには次の行が含まれます。

タイムスタンプ
0 個以上のディメンション
1 つ以上のメジャー

メトリック

DataFeedMetric は、特定のビジネスプロセスの状態を監視および評価するために使用される定量化可能なメジャーです。ディメンションに分割された複数の時系列値を組み合わせることができます。たとえば、web health のメトリックには、user count と en-us market のディメンションが含まれている場合があります。

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration は、時系列ごとに必要であり、時系列のポイントが異常であるかどうかを判断します。

異常インシデント&

検出構成がメトリックに適用されると、 AnomalyIncidentその中の系列にが含まれるたびに s DataPointAnomalyが生成されます。

アラート:

をトリガーする必要がある異常を AnomalyAlert構成できます。異なる設定で複数のアラートを設定できます。たとえば、ビジネスへの影響が少ない異常に対するアラートを作成し、さらに重要なアラートに対して別のアラートを作成できます。

通知フック

Metrics Advisor を使用すると、リアルタイムのアラートを作成し、サブスクライブすることができます。これらのアラートは、や WebNotificationHookなどのEmailNotificationHook通知フックを使用して、インターネット経由で送信されます。

サンプルまたはデータソースからデータフィードを追加する

Metrics Advisor では、さまざまな種類のデータソースの接続がサポートされています。ここでは、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 Metrics Advisor クライアントは、 Azure Core で定義されている例外を発生させます。

ログの記録

このライブラリでは、ログ記録に標準のログライブラリが使用されます。

HTTP セッション (URL、ヘッダーなど) に関する基本情報は、レベルで INFO ログに記録されます。

要求/応答本文や未設定ヘッダーなど、詳細なDEBUGレベルのログ記録は、クライアントで有効にすることも、キーワード引数を使用して操作ごとに有効にlogging_enableすることもできます。

SDK ログに関する完全なドキュメントと例については、こちらを参照してください。

次のステップ

その他のサンプルコード

詳細については、 README のサンプルを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。詳細については、「 cla.microsoft.com」を参照してください。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

次の方法で共有

Python 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

主要な概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

DataFeed

メトリック

AnomalyDetectionConfiguration

異常インシデント&

アラート:

通知フック

例

サンプルまたはデータソースからデータフィードを追加する

インジェストの状態を確認する

異常検出を構成する

アラートを構成する

異常検出の結果を照会する

インシデントのクエリ

クエリの根本原因

異常アラートを受信するためのフックを追加する

非同期 API

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプルコード

共同作成

その他のリソース

次の方法で共有

Python 用 Azure Metrics Advisor クライアント ライブラリ - バージョン 1.0.0

作業の開始

パッケージをインストールする

前提条件

クライアントを認証する

主要な概念

MetricsAdvisorClient

MetricsAdvisorAdministrationClient

DataFeed

メトリック

AnomalyDetectionConfiguration

異常インシデント&

アラート:

通知フック

例

サンプルまたはデータ ソースからデータ フィードを追加する

インジェストの状態を確認する

異常検出を構成する

アラートを構成する

異常検出の結果を照会する

インシデントのクエリ

クエリの根本原因

異常アラートを受信するためのフックを追加する

非同期 API

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプル コード

共同作成

その他のリソース

Python 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.0.0

サンプルまたはデータソースからデータフィードを追加する

その他のサンプルコード