Klientská knihovna Azure Metrics Advisoru pro Python – verze 1.0.0

Článek
04/05/2023

Metrics Advisor je škálovatelná platforma pro monitorování, upozorňování a analýzu původních příčin v reálném čase. Poradce pro metriky slouží k:

Analýza multidimenzionálních dat z více zdrojů dat
Identifikace a korelace anomálií
Konfigurace a vyladění modelu detekce anomálií, který se používá u vašich dat
Diagnostika anomálií a pomoc s analýzou původní příčiny

Zdrojový kód | Balíček (Pypi) | Referenční dokumentace k | rozhraní API Dokumentace k | produktu Vzorky

Začínáme

Instalace balíčku

Nainstalujte klientskou knihovnu Azure Metrics Advisor pro Python pomocí pipu:

pip install azure-ai-metricsadvisor --pre

Požadavky

K použití tohoto balíčku se vyžaduje Python 2.7 nebo 3.6 nebo novější.
K použití tohoto balíčku potřebujete předplatné Azure a službu Metrics Advisor .

Ověření klienta

K ověření klienta budete potřebovat dva klíče:

Klíč předplatného vašeho prostředku Metrics Advisor. Najdete ho v části Klíče a koncový bod vašeho prostředku v Azure Portal.
Klíč rozhraní API pro vaši instanci Advisoru pro metriky Najdete ho na webovém portálu nástroje Metrics Advisor v části Klíče rozhraní API v levé navigační nabídce.

Pomocí klíčů můžeme vytvořit nový MetricsAdvisorClient nebo 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))

Klíčové koncepty

MetricsAdvisorClient

MetricsAdvisorClient pomáhá s:

výpis incidentů
výpis původních příčin incidentů
načítání původních dat časových řad a dat časových řad obohacených službou.
upozornění na výpis
přidání zpětné vazby k vyladění modelu

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient vám umožní

správa datových kanálů
správa konfigurací detekce anomálií
správa konfigurací upozornění na anomálie
správa háčků

Datový kanál

A DataFeed je to, co Služba Metrics Advisor ingestuje z vašeho zdroje dat, jako je Cosmos DB nebo SQL Server. Datový kanál obsahuje řádky:

Časová razítka
nula nebo více dimenzí
jedno nebo více opatření

Metric

A DataFeedMetric je kvantifikovatelná míra, která slouží k monitorování a hodnocení stavu konkrétního obchodního procesu. Může se jednat o kombinaci více hodnot časových řad rozdělených do dimenzí. Metrika stavu webu může například obsahovat dimenze pro počet uživatelů a trh en-us.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration se vyžaduje pro každou časovou řadu a určuje, jestli je bod v časové řadě anomálií.

Incident anomálie &

Po použití konfigurace detekce na metriky se s vygenerují vždy, AnomalyIncidentkdyž jakákoli řada v rámci této řady obsahuje DataPointAnomaly.

Výstrahy

Můžete nakonfigurovat, které anomálie by měly aktivovat AnomalyAlert. Můžete nastavit více výstrah s různými nastaveními. Můžete například vytvořit výstrahu pro anomálie s nižším obchodním dopadem a další pro důležitější výstrahy.

Oznamovací háček

Nástroj Metrics Advisor umožňuje vytvářet a odebírat upozornění v reálném čase. Tato upozornění se odesílají přes internet pomocí oznamovacího háku, jako je nebo EmailNotificationHookWebNotificationHook.

Příklady

Přidání datového kanálu z ukázky nebo zdroje dat
Kontrola stavu příjmu dat
Konfigurace detekce anomálií
Konfigurace konfigurace upozornění
Dotazování na výsledky detekce anomálií
Dotazování na incidenty
Původní příčiny dotazu
Přidání háků pro příjem upozornění na anomálie

Přidání datového kanálu z ukázky nebo zdroje dat

Poradce pro metriky podporuje propojení různých typů zdrojů dat. Tady je ukázka ingestování dat z 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

Kontrola stavu příjmu dat

Po zahájení příjmu dat můžeme zkontrolovat stav příjmu dat.

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))

Konfigurace detekce anomálií

I když se na každou metriku automaticky použije výchozí konfigurace detekce, můžeme vyladit režimy detekce používané u našich dat vytvořením přizpůsobené konfigurace detekce anomálií.

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

Konfigurace konfigurace upozornění

Pak nakonfigurujeme, za jakých podmínek se má výstraha aktivovat.

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

Dotazování na výsledky detekce anomálií

Na výstrahy a anomálie se můžeme dotazovat.

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))

Dotazování na incidenty

Můžeme se na incidenty dotazovat na konfiguraci detekce.

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))

Původní příčiny dotazu

Můžeme se také dotazovat na původní příčiny incidentu.

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))

Přidání háků pro příjem upozornění na anomálie

Můžeme přidat nějaké háčky, abychom při aktivaci upozornění mohli získat zpět hovor.

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

Asynchronní rozhraní API

Tato knihovna obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.6 nebo novějším. Abyste ho mohli používat, musíte nejprve nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k 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)
)

Poradce při potížích

Obecné

Klienti Azure Metrics Advisoru budou vyvolávat výjimky definované v Azure Core.

protokolování

Tato knihovna používá pro protokolování standardní knihovnu protokolování .

Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na INFO úrovni.

Protokolování podrobných DEBUG úrovní, včetně těl požadavků/odpovědí a nereagovaných hlaviček, je možné povolit u klienta nebo pro jednotlivé operace pomocí argumentu klíčového logging_enable slova.

Kompletní dokumentaci k protokolování sady SDK s příklady najdete tady.

Další kroky

Další ukázkový kód

Další podrobnosti najdete v ukázkách SOUBORU README.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete na cla.microsoft.com.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.

Sdílet prostřednictvím