Biblioteca de clientes do Assistente de Métricas do Azure para Python – versão 1.0.0

Artigo
04/05/2023

O Assistente de Métricas é uma plataforma de análise de causa raiz, monitoramento de séries em tempo real escalonável. Use o Assistente de Métricas para:

Analisar dados multidimensionais de várias fontes de dados
Identificar e correlacionar anomalias
Configurar e ajustar o modelo de detecção de anomalias usado nos dados
Diagnosticar anomalias e ajudar com a análise de causa raiz

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

Introdução

Instalar o pacote

Instale a biblioteca de clientes do Assistente de Métricas do Azure para Python com pip:

pip install azure-ai-metricsadvisor --pre

Pré-requisitos

Python 2.7, ou 3.6 ou posteriores, é necessário para usar esse pacote.
Você precisa de uma assinatura do Azure e de um assistente de métricas para usar esse pacote.

Autenticar o cliente

Você precisará de duas chaves para autenticar o cliente:

A chave de assinatura para o recurso do Assistente de Métricas. Encontre-a na seção Chaves e ponto de extremidade de seu recurso no portal do Azure.
A chave de API de sua instância do Assistente de Métricas. Encontre-a no portal da Web do Assistente de Métricas, em Chaves de 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))

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorClient ajuda com:

listando incidentes
listar causas raiz de incidentes
recuperando dados de série temporal originais e dados de série temporal enriquecidos pelo serviço.
listar alertas
adicionando comentários para ajustar seu modelo

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient permite que você

gerenciar feeds de dados
gerenciar configurações de detecção de anomalias
gerenciar configurações de alerta de anomalias
gerenciar ganchos

DataFeed

Um DataFeed é o que o Assistente de Métricas ingere de sua fonte de dados, como o Cosmos DB ou um SQL Server. Um feed de dados contém linhas de:

carimbos de data/hora
zero ou mais dimensões
uma ou mais medidas

Métrica

Uma DataFeedMetric é uma medida quantificável usada para monitorar e avaliar o status de um processo empresarial específico. Pode ser uma combinação de vários valores de série temporal divididos em dimensões. Por exemplo, uma métrica de integridade da Web pode conter dimensões para contagem de usuários e mercado en-us.

AnomalyDetectionConfiguration

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

Incidente de anomalias &

Depois que uma configuração de detecção é aplicada às métricas, AnomalyIncidents são gerados sempre que qualquer série dentro dela tem um DataPointAnomaly.

Alerta

Você pode configurar quais anomalias devem disparar um AnomalyAlert. Você pode definir vários alertas com configurações diferentes. Por exemplo, você pode criar um alerta para anomalias com menor impacto nos negócios e outro para alertas mais importantes.

Gancho de notificação

O Assistente de Métricas permite criar e assinar alertas em tempo real. Esses alertas são enviados pela Internet usando um gancho de notificação como EmailNotificationHook ou WebNotificationHook.

Exemplos

Adicionar um feed de dados de um exemplo ou fonte de dados
Verificar o status da ingestão
Configurar a configuração de detecção de anomalias
Configurar a configuração de alerta
Resultados da detecção de anomalias de consulta
Consultar incidentes
Causas raiz da consulta
Adicionar ganchos para receber alertas de anomalias

Adicionar um feed de dados de uma amostra ou fonte de dados

O Assistente de Métricas dá suporte à conexão de diferentes tipos de fontes de dados. Este é um exemplo de ingestão de dados do 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 status da ingestão

Depois de iniciarmos a ingestão de dados, poderemos verificar o status 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))

Definir a configuração da detecção de anomalias

Embora uma configuração de detecção padrão seja aplicada automaticamente a cada métrica, podemos ajustar os modos de detecção usados em nossos dados criando uma configuração de detecçã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

Definir a configuração de alerta

Em seguida, vamos configurar em quais condições um alerta precisa ser disparado.

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

Consultar os resultados da detecção de anomalias

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

Consultar incidentes

Podemos consultar os incidentes para uma configuração de detecçã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 raiz da consulta

Também podemos consultar as causas raiz 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))

Adicionar ganchos para receber alertas de anomalias

Podemos adicionar alguns ganchos para que, quando um alerta for disparado, possamos receber a 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"
    )
)

APIs assíncronas

Essa biblioteca inclui uma API assíncrona completa com suporte no Python 3.6+. Para usá-lo, primeiro você deve instalar um transporte assíncrono, como aiohttp. Confira a documentação do azure-core 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)
)

Solução de problemas

Geral

Os clientes do Assistente de Métricas do Azure gerarão exceções definidas no Azure Core.

Log

Essa biblioteca usa a biblioteca de log padrão para registro em log.

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

O log de nível detalhado DEBUG , incluindo corpos de solicitação/resposta e cabeçalhos não redigidos , pode ser habilitado no cliente ou por operação com o logging_enable argumento de palavra-chave .

Confira a documentação completa de registro em log do SDK com exemplos aqui.

Próximas etapas

Mais códigos de exemplo

Para obter mais detalhes, consulte os exemplos README.

Contribuição

Este projeto aceita contribuições e sugestões. A maioria das contribuições exige que você concorde com um CLA (Contrato de Licença do Colaborador) declarando que você tem o direito de nos conceder, e de fato concede, os direitos de usar sua contribuição. Para obter detalhes, visite cla.microsoft.com.

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Compartilhar via