Biblioteca cliente Azure Metrics Advisor para Python - versão 1.0.0

Artigo
04/05/2023

Metrics Advisor é uma plataforma de monitorização, alerta e análise de causas de raiz escaláveis em tempo real. Utilizar o Advisor métrica para:

Analisar dados multidimensionais de várias fontes de dados
Identificar e correlacionar anomalias
Configure e afina o modelo de deteção de anomalias utilizado nos seus dados
Diagnosticar anomalias e ajudar na análise da causa raiz

Código fonte | Pacote (Pypi) | Documentação de | referência da API Documentação | do produto Amostras

Introdução

Instale o pacote

Instale a biblioteca cliente Azure Metrics Advisor para Python com pip:

pip install azure-ai-metricsadvisor --pre

Pré-requisitos

Python 2.7, ou 3.6 ou mais tarde é obrigado a usar este pacote.
Você precisa de uma assinatura Azure, e um serivce Metrics Advisor para usar este pacote.

Autenticar o cliente

Vai precisar de duas chaves para autenticar o cliente:

A chave de subscrição do seu recurso Metrics Advisor. Pode encontrar isto na secção Chaves e Ponto Final do seu recurso na portal do Azure.
A chave API para o seu exemplo de Conselheiro de Métricas. Pode encontrá-lo no portal web para Metrics Advisor, nas teclas API no menu de navegação à esquerda.

Podemos usar as chaves para criar um novo MetricsAdvisorClient ou 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))

Conceitos-chave

MetricsAdvisorClient

MetricsAdvisorClient ajuda com:

enumeração de incidentes
enumerando as causas de raiz dos incidentes
recuperando dados originais de séries de tempo e dados de séries de tempo enriquecidos pelo serviço.
alertas de listagem
adicionar feedback para sintonizar o seu modelo

MétricasAdvisorDissinsecimento

MetricsAdvisorAdministrationClient permite-lhe

gerir feeds de dados
gerir configurações de deteção de anomalias
gerir configurações de alerta de anomalias
gerir ganchos

DataFeed

A DataFeed é o que o Metrics Advisor ingere a partir da sua fonte de dados, como o Cosmos DB ou um servidor SQL. Um feed de dados contém linhas de:

mps de tempos
zero ou mais dimensões
uma ou mais medidas

Metric

A DataFeedMetric é uma medida quantificável que é usada para monitorizar e avaliar o estado de um processo de negócio específico. Pode ser uma combinação de múltiplos valores de séries de tempo divididos em dimensões. Por exemplo, uma métrica de saúde web pode conter dimensões para a contagem de utilizadores e para o mercado en-us.

AlteraçãoDetecçãoConfiguration

AnomalyDetectionConfiguration é necessário para cada série de tempo, e determina se um ponto na série de tempo é uma anomalia.

Incidente de Anomalia &

Após a aplicação de uma configuração de deteção às métricas, AnomalyIncidents são gerados sempre que qualquer série dentro tem um DataPointAnomaly.

Alerta

Pode configurar quais anomalias devem desencadear um AnomalyAlert. Pode definir vários alertas com diferentes configurações. Por exemplo, pode criar um alerta para anomalias com menor impacto no negócio, e outro para alertas mais importantes.

Gancho de Notificação

O Metrics Advisor permite criar e subscrever alertas em tempo real. Estes alertas são enviados através da internet, utilizando um gancho de notificação como EmailNotificationHook ou WebNotificationHook.

Exemplos

Adicione um feed de dados a partir de uma amostra ou fonte de dados
Verificar o estado da ingestão
Configuração de deteção de anomalias configuração configure
Configuração de alerta de configuração
Resultados de deteção de anomalias de consulta
Incidentes de consulta
Causas de raiz de consulta
Adicione ganchos para receber alertas de anomalia

Adicione um feed de dados a partir de uma amostra ou fonte de dados

O Metrics Advisor suporta a ligação de diferentes tipos de fontes de dados. Aqui está uma amostra para ingerir dados de 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

Verificar o estado da ingestão

Depois de começarmos a ingestão de dados, podemos verificar o estado da ingestão.

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

Configuração de deteção de anomalias configuração configure

Enquanto uma configuração de deteção padrão é aplicada automaticamente a cada métrica, podemos sintonizar os modos de deteção utilizados nos nossos dados criando uma configuração de deteção de anomalias personalizada.

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

Configuração de alerta de configuração

Então vamos configurar em que condições um alerta precisa ser desencadeado.

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

Resultados de deteção de anomalias de consulta

Podemos consultar os alertas e anomalias.

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

Incidentes de consulta

Podemos consultar os incidentes para uma configuração de deteção.

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

Causas de raiz de consulta

Também podemos consultar as causas de um incidente.

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

Adicione ganchos para receber alertas de anomalia

Podemos adicionar alguns ganchos para que quando um alerta for acionado, possamos receber uma chamada de volta.

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

Async APIs

Esta biblioteca inclui uma API completa assínca suportada em Python 3.6+. Para usá-lo, primeiro deve instalar um transporte de async, como aiohttp. Consulte a documentação do núcleo azul para obter mais informações.

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

Resolução de problemas

Geral

Os clientes Azure Metrics Advisor irão levantar exceções definidas no Azure Core.

Registo

Esta biblioteca utiliza a biblioteca de registos padrão para registar registos.

Informações básicas sobre sessões HTTP (URLs, cabeçalhos, etc.) são registadas ao INFO nível.

A registo de nível detalhado DEBUG , incluindo os órgãos de pedido/resposta e os cabeçalhos não redigidos , pode ser ativado no cliente ou por operação com o argumento da logging_enable palavra-chave.

Consulte a documentação completa do registo SDK com exemplos aqui.

Passos seguintes

Mais código de amostra

Para mais detalhes consulte as amostras README.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para mais detalhes, visite cla.microsoft.com.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para mais informações consulte o Código de Conduta FAQ ou contacte opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Partilhar via