Azure Metrics Advisor-Clientbibliothek für Python– Version 1.0.0

Artikel
04/05/2023

Metrics Advisor ist eine skalierbare Plattform für Echtzeitzeitreihenüberwachung, Warnungen und Ursachenanalyse. Metrics Advisor ermöglicht Folgendes:

Analysieren mehrdimensionaler Daten aus mehreren Datenquellen
Identifizieren und Korrelieren von Anomalien
Konfigurieren und Optimieren des für Ihre Daten verwendeten Anomalieerkennungsmodells
Diagnostizieren von Anomalien und Bereitstellen von Unterstützung bei der Ursachenanalyse

Quellcode | Paket (Pypi) | API-Referenzdokumentation | Produktdokumentation | Beispiele

Erste Schritte

Installieren des Pakets

Installieren Sie die Azure Metrics Advisor-Clientbibliothek für Python mit pip:

pip install azure-ai-metricsadvisor --pre

Voraussetzungen

Für die Verwendung dieses Pakets ist Python 2.7 bzw. 3.6 oder höher erforderlich.
Sie benötigen ein Azure-Abonnement und eine Metrics Advisor-Instanz , um dieses Paket verwenden zu können.

Authentifizieren des Clients

Sie benötigen zwei Schlüssel, um den Client zu authentifizieren:

Der Abonnementschlüssel für Ihre Metrics Advisor-Ressource. Sie finden ihn im Azure-Portal im Abschnitt Schlüssel und Endpunkt für Ihre Ressource.
Der API-Schlüssel für Ihre Metrics Advisor-Instanz. Diesen finden Sie im Webportal für den Metrics Advisor im linken Navigationsmenü unter API-Schlüssel.

Wir können die Schlüssel verwenden, um eine neue MetricsAdvisorClient oder MetricsAdvisorAdministrationClientzu erstellen.

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

Wichtige Begriffe

MetricsAdvisorClient

MetricsAdvisorClient hilft bei:

Auflisten von Vorfällen
Auflisten der Grundursachen von Vorfällen
Abrufen der ursprünglichen Zeitreihendaten und Zeitreihendaten, die durch den Dienst angereichert werden.
Auflisten von Warnungen
Hinzufügen von Feedback zum Optimieren Ihres Modells

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient ermöglicht Ihnen,

Verwalten von Datenfeeds
Verwalten von Anomalieerkennungskonfigurationen
Verwalten von Anomaliewarnungskonfigurationen
Verwalten von Hooks

DataFeed

Ein DataFeed erfasst Metrics Advisor aus Ihrer Datenquelle, z. B. Cosmos DB oder einem SQL Server. Ein Datenfeed enthält Zeilen mit den folgenden Informationen:

Timestamps
Null oder mehr Dimensionen
eine oder mehrere Measures

Metrik

Eine Metrik (DataFeedMetric) ist ein quantifizierbares Measure, das zum Überwachen und Bewerten des Status eines bestimmten Geschäftsprozesses verwendet wird. Hierbei kann es sich um eine Kombination aus mehreren Zeitreihen handeln, die in Dimensionen unterteilt sind. Eine Metrik vom Typ Webintegrität kann beispielsweise Dimensionen für die Benutzeranzahl und den US-amerikanischen Markt enthalten.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration ist für jede Zeitreihe erforderlich und bestimmt, ob ein Punkt in der Zeitreihe eine Anomalie ist.

Anomalievorfall &

Nachdem eine Erkennungskonfiguration auf Metriken angewendet wurde, werden immer dann generiert, AnomalyIncidentwenn eine Reihe darin einen DataPointAnomalyenthält.

Warnung

Sie können konfigurieren, welche Anomalien eine AnomalyAlertauslösen sollen. Sie können mehrere Warnungen mit unterschiedlichen Einstellungen festlegen. Sie können beispielsweise eine Warnung für Anomalien mit geringeren geschäftlichen Auswirkungen und eine weitere warnung für wichtigere Warnungen erstellen.

Benachrichtigungshook

Mit Metrics Advisor können Sie Echtzeitwarnungen erstellen und abonnieren. Diese Warnungen werden über das Internet gesendet, indem ein Benachrichtigungshook wie EmailNotificationHook oder verwendet WebNotificationHookwird.

Beispiele

Hinzufügen eines Datenfeeds aus einem Beispiel oder einer Datenquelle
Überprüfen des Erfassungsstatus
Konfigurieren der Anomalieerkennungskonfiguration
Konfigurieren der Warnungskonfiguration
Abfragen von Anomalieerkennungsergebnissen
Abfragen von Incidents
Abfragestammursachen
Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen

Hinzufügen eines Datenfeeds aus einem Beispiel oder aus einer Datenquelle

Metrics Advisor unterstützt die Verbindung von unterschiedlichen Typen von Datenquellen. Hier ist ein Beispiel für die Erfassung von Daten aus SQL Server angegeben.

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

Überprüfen des Erfassungsstatus

Nach dem Starten der Datenerfassung können wir den Erfassungsstatus überprüfen.

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

Konfigurieren der Anomalieerkennung

Während eine Standarderkennungskonfiguration automatisch auf jede Metrik angewendet wird, können wir die für unsere Daten verwendeten Erkennungsmodi optimieren, indem wir eine benutzerdefinierte Anomalieerkennungskonfiguration erstellen.

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

Konfigurieren von Warnungen

Anschließend konfigurieren wir, unter welchen Bedingungen eine Warnung ausgelöst werden muss.

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

Abfragen von Anomalieerkennungsergebnissen

Wir können die Warnungen und Anomalien abfragen.

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

Abfragen von Incidents

Wir können die Incidents für eine Erkennungskonfiguration abfragen.

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

Abfragestammursachen

Wir können auch die Grundursachen eines Incidents abfragen.

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

Hinzufügen von Hooks zum Empfangen von Anomaliewarnungen

Wir können einige Hooks hinzufügen, sodass wir beim Auslösen einer Warnung einen Rückruf erhalten können.

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

Asynchrone APIs

Diese Bibliothek enthält eine vollständige asynchrone API, die unter Python 3.6 und höher unterstützt wird. Um es verwenden zu können, müssen Sie zuerst einen asynchronen Transport installieren, z. B. aiohttp. Weitere Informationen finden Sie in der Dokumentation zu 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)
)

Problembehandlung

Allgemein

Die Azure Metrics Advisor-Clients lösen ausnahmen aus, die in Azure Core definiert sind.

Protokollierung

Diese Bibliothek verwendet die Standardprotokollbibliothek für die Protokollierung.

Grundlegende Informationen zu HTTP-Sitzungen (URLs, Header usw.) werden auf ebener Ebene INFO protokolliert.

Die Protokollierung auf detaillierter DEBUG Ebene, einschließlich Anforderungs-/Antworttexten und nicht ausgeführten Headern, kann auf dem Client oder pro Vorgang mit dem logging_enable Schlüsselwortargument aktiviert werden.

Die vollständige SDK-Protokollierungsdokumentation mit Beispielen finden Sie hier.

Nächste Schritte

Weiterer Beispielcode

Weitere Informationen finden Sie in der Infodatei zu Beispielen.

Mitwirken

Beiträge und Vorschläge für dieses Projekt sind willkommen. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. Weitere Informationen finden Sie unter cla.microsoft.com.

Für dieses Projekt gelten die Microsoft-Verhaltensregeln für Open Source (Microsoft Open Source Code of Conduct). Weitere Informationen finden Sie in den häufig gestellten Fragen zum Verhaltenskodex. Sie können sich auch an opencode@microsoft.com wenden, wenn Sie weitere Fragen oder Anmerkungen haben.

Freigeben über