Azure Metrics Advisor-klientbibliotek för Python – version 1.0.0

Metrics Advisor är en skalbar plattform för övervakning, aviseringar och rotorsaksanalys i realtid. Använd Metrics Advisor för att:

• Analysera flerdimensionella data från flera datakällor
• Identifiera och korrelera avvikelser
• Konfigurera och finjustera modellen för avvikelseidentifiering som används för dina data
• Diagnostisera avvikelser och hjälp med rotorsaksanalys

| Källkod Paket (Pypi) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Installera paketet

Installera Azure Metrics Advisor-klientbiblioteket för Python med pip:

pip install azure-ai-metricsadvisor --pre

Förutsättningar

• Python 2.7 eller 3.6 eller senare krävs för att använda det här paketet.
• Du behöver en Azure-prenumeration och en Metrics Advisor-tjänst för att använda det här paketet.

Autentisera klienten

Du behöver två nycklar för att autentisera klienten:

1. Prenumerationsnyckeln för din Metrics Advisor-resurs. Du hittar detta i avsnittet Nycklar och slutpunkt för din resurs i Azure Portal.
2. API-nyckeln för din Metrics Advisor-instans. Du hittar detta i webbportalen för Metrics Advisor i API-nycklar på den vänstra navigeringsmenyn.

Vi kan använda nycklarna för att skapa en ny MetricsAdvisorClient eller 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))

Viktiga begrepp

MetricsAdvisorClient

MetricsAdvisorClient hjälper till med:

• lista incidenter
• lista rotorsaker till incidenter
• hämtar ursprungliga tidsseriedata och tidsseriedata som berikats av tjänsten.
• visa aviseringar
• lägga till feedback för att finjustera din modell

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient gör att du kan

• hantera dataflöden
• hantera konfigurationer för avvikelseidentifiering
• hantera konfigurationer för avvikelseaviseringar
• hantera krokar

Datafeed

A DataFeed är vad Metrics Advisor matar in från din datakälla, till exempel Cosmos DB eller en SQL-server. En datafeed innehåller rader med:

• Tidsstämplar
• noll eller fler dimensioner
• ett eller flera mått

Metric

En DataFeedMetric är ett kvantifierbart mått som används för att övervaka och utvärdera status för en specifik affärsprocess. Det kan vara en kombination av flera tidsserievärden indelade i dimensioner. Ett webbhälsomått kan till exempel innehålla dimensioner för antalet användare och en-us-marknaden.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration krävs för varje tidsserie och avgör om en punkt i tidsserien är en avvikelse.

Avvikelseincident &

När en identifieringskonfiguration har tillämpats AnomalyIncidentpå mått genereras s när alla serier i den har en DataPointAnomaly.

Varning

Du kan konfigurera vilka avvikelser som ska utlösa en AnomalyAlert. Du kan ange flera aviseringar med olika inställningar. Du kan till exempel skapa en avisering för avvikelser med lägre affärspåverkan och en annan för viktigare aviseringar.

Notification Hook

Med Metrics Advisor kan du skapa och prenumerera på realtidsaviseringar. Dessa aviseringar skickas via Internet med hjälp av en meddelandehook som EmailNotificationHook eller WebNotificationHook.

Exempel

• Lägga till ett dataflöde från ett exempel eller en datakälla
• Kontrollera datainmatningsstatus
• Konfigurera konfiguration av avvikelseidentifiering
• Konfigurera aviseringskonfiguration
• Fråga avvikelseidentifieringsresultat
• Köra frågor mot incidenter
• Rotorsaker till frågor
• Lägga till krokar för att ta emot avvikelseaviseringar

Lägga till ett dataflöde från ett exempel eller en datakälla

Metrics Advisor stöder anslutning av olika typer av datakällor. Här är ett exempel på hur du matar in data från 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

Kontrollera datainmatningsstatus

När vi har startat datainmatningen kan vi kontrollera inmatningsstatusen.

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

Konfigurera konfiguration av avvikelseidentifiering

Även om en standardidentifieringskonfiguration tillämpas automatiskt på varje mått kan vi justera de identifieringslägen som används för våra data genom att skapa en anpassad konfiguration för avvikelseidentifiering.

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

Konfigurera aviseringskonfiguration

Sedan konfigurerar vi i vilka villkor en avisering måste utlösas.

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

Fråga avvikelseidentifieringsresultat

Vi kan köra frågor mot aviseringar och avvikelser.

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

Köra frågor mot incidenter

Vi kan fråga incidenterna om en identifieringskonfiguration.

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

Rotorsaker till frågor

Vi kan också fråga rotorsaken till en incident

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

Lägga till krokar för att ta emot avvikelseaviseringar

Vi kan lägga till några hookar så att vi kan få ett återanrop när en avisering utlöses.

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

Asynkrona API:er

Det här biblioteket innehåller ett fullständigt asynkront API som stöds i Python 3.6+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i azure-core-dokumentationen .

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

Felsökning

Allmänt

Azure Metrics Advisor-klienterna genererar undantag som definierats i Azure Core.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning.

Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO nivå.

Detaljerad DEBUG nivåloggning, inklusive begärande-/svarskroppar och oredigerade rubriker, kan aktiveras på klienten eller per åtgärd med nyckelordsargumentet logging_enable .

Se fullständig SDK-loggningsdokumentation med exempel här.

Nästa steg

Mer exempelkod

Mer information finns i README-exempel.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns i cla.microsoft.com.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.