Libreria client di Azure Metrics Advisor per Python - versione 1.0.0

Articolo
04/05/2023

Metrics Advisor è un monitoraggio di serie in tempo reale scalabile, avvisi e piattaforma di analisi della causa radice. Usare Advisor metriche per:

Analizzare dati multidimensionali da più origini dati
Identificare e correlare le anomalie
Configurare e ottimizzare il modello di rilevamento anomalie usato sui dati
Diagnosticare anomalie e assistenza con l'analisi della causa radice

Codice | sorgente Pacchetto (Pypi) | Documentazione di | riferimento sulle API Documentazione | del prodotto Campioni

Introduzione

Installare il pacchetto

Installare la libreria client di Azure Metrics Advisor per Python con pip:

pip install azure-ai-metricsadvisor --pre

Prerequisiti

Python 2.7 o 3.6 o versione successiva è necessario per usare questo pacchetto.
È necessaria una sottoscrizione di Azure e una metrica advisor serivce per l'uso di questo pacchetto.

Autenticare il client

Sono necessarie due chiavi per autenticare il client:

Chiave di sottoscrizione della risorsa Metrics Advisor. È possibile trovarla nella sezione Chiavi ed endpoint della risorsa nel portale di Azure.
La chiave API dell'istanza di Advisor metriche. È possibile trovarla in Chiavi API nel menu di spostamento a sinistra del portale Web per Advisor metriche.

È possibile usare le chiavi per creare un nuovo MetricsAdvisorClient oggetto o 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))

Concetti chiave

MetricsAdvisorClient

MetricsAdvisorClient aiuta con:

elencare gli eventi imprevisti
elencare le cause radice degli eventi imprevisti
recupero dei dati originali della serie temporale e dei dati della serie temporale arricchiti dal servizio.
elencare gli avvisi
aggiunta di commenti e suggerimenti per ottimizzare il modello

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient consente di

gestire i feed di dati
gestire configurazioni di rilevamento anomalie
gestire configurazioni di avviso anomalie
gestire gli hook

DataFeed

Un DataFeed oggetto è l'inserimento di Metrics Advisor dall'origine dati, ad esempio Cosmos DB o un server SQL. Un feed di dati contiene righe di:

timestamp
zero o più dimensioni
una o più misure

Metrica

Per DataFeedMetric si intende una misura quantificabile usata per monitorare e valutare lo stato di un processo aziendale specifico. Può essere una combinazione di più valori di serie temporali divisi in dimensioni. Una metrica di integrità Web può ad esempio contenere dimensioni relative al numero di utenti e al mercato statunitense.

AnomalyDetectionConfiguration

AnomalyDetectionConfiguration è necessario per ogni serie temporale e determina se un punto della serie temporale è un'anomalia.

Evento imprevisto dell'anomalia &

Dopo l'applicazione di una configurazione di rilevamento alle metriche, AnomalyIncidents viene generato ogni volta che qualsiasi serie all'interno ha un DataPointAnomalyoggetto .

Avviso

È possibile configurare quali anomalie devono attivare un AnomalyAlertoggetto . È possibile impostare più avvisi con impostazioni diverse. Ad esempio, è possibile creare un avviso per anomalie con un impatto aziendale inferiore e un altro per avvisi più importanti.

Hook di notifica

Advisor metriche consente di creare e sottoscrivere avvisi in tempo reale. Questi avvisi vengono inviati tramite Internet usando un hook di notifica come EmailNotificationHook o WebNotificationHook.

Esempio

Aggiungere un feed di dati da un esempio o da un'origine dati
Controllare lo stato di inserimento
Configurare la configurazione del rilevamento anomalie
Configurare la configurazione degli avvisi
Eseguire query sui risultati del rilevamento anomalie
Eventi imprevisti di query
Cause radice di query
Aggiungere hook per la ricezione di avvisi anomalie

Aggiungere un feed di dati da un esempio o da un'origine dati

Advisor metriche supporta la connessione di diversi tipi di origini dati. Ecco un esempio di inserimento dati da 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

Controllare lo stato dell'inserimento

Dopo aver avviato l'inserimento dati, è possibile controllarne lo stato.

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

Configurare il rilevamento anomalie

Anche se una configurazione di rilevamento predefinita viene applicata automaticamente a ogni metrica, è possibile ottimizzare le modalità di rilevamento usate nei dati creando una configurazione di rilevamento anomalie personalizzata.

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

Configurare gli avvisi

Verrà quindi configurato in quali condizioni deve essere attivato un avviso.

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

Eseguire query sui risultati del rilevamento anomalie

È possibile eseguire query sugli avvisi e le anomalie.

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

Eventi imprevisti di query

È possibile eseguire query sugli eventi imprevisti per una configurazione di rilevamento.

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

Cause radice di query

È anche possibile eseguire query sulle cause radice di un evento imprevisto

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

Aggiungere hook per la ricezione di avvisi anomalie

È possibile aggiungere alcuni hook in modo che quando viene attivato un avviso, è possibile tornare indietro.

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 asincrone

Questa libreria include un'API asincrona completa supportata in Python 3.6+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di 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)
)

Risoluzione dei problemi

Generale

I client di Azure Metrics Advisor genereranno eccezioni definite in Azure Core.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione.

Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a INFO livello.

La registrazione dettagliata DEBUG a livello, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate , può essere abilitata nel client o per operazione con l'argomento logging_enable parola chiave.

Vedere la documentazione completa sulla registrazione sdk con esempi qui.

Passaggi successivi

Altro codice di esempio

Per altre informazioni, vedere gli esempi README.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, visitare cla.microsoft.com.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.

Condividi tramite