Partilhar via

Biblioteca de clientes do Assistente de Métricas do Azure para Java – versão 1.1.19

  • Artigo

O Assistente de Métricas do Azure é um novo Serviço Cognitivo que usa a IA de decisão baseada em série temporal para identificar e ajudar a solucionar problemas de serviços online e monitorar a integridade dos negócios automatizando a fatia e os dados de negóciosFeedMetrics.

Código-fonte | Pacote (Maven) | Documentação | de referência da APIDocumentação do | produtoAmostras

Introdução

Pré-requisitos

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga (disponibilidade geral) da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

e inclua a dependência direta na seção dependências sem a marca de versão, conforme mostrado abaixo.

<dependencies>
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-metricsadvisor</artifactId>
    </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira. Nota: Esta versão tem como destino a versão v1.0 da API de serviço do Assistente de Métricas do Azure.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-metricsadvisor</artifactId>
    <version>1.1.19</version>
</dependency>

Criar um recurso do Assistente de Métricas

Autenticar o cliente

Para interagir com o serviço assistente de métricas, você precisará criar uma instância do cliente do Assistente de Métricas. Os clientes assíncronos e síncronos podem ser criados usando MetricsAdvisorClientBuilder. Invocar buildClient() criará o cliente síncrono, enquanto a invocação buildAsyncClient criará seu equivalente assíncrono.

Pesquisando o ponto de extremidade

Você pode encontrar o ponto de extremidade do recurso do Assistente de Métricas no Portal do Azure ou na CLI do Azure.

# Get the endpoint for the resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

Criar um cliente do MetricsAdvisor usando MetricsAdvisorKeyCredential

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. Você pode encontrá-lo no portal da Web para o Assistente de Métricas, em Chaves de API no menu de navegação à esquerda.

Depois de ter as duas chaves e o ponto de extremidade, você pode usar a MetricsAdvisorKeyCredential classe para autenticar os clientes da seguinte maneira:

Criar um cliente do Assistente de Métricas usando MetricsAdvisorKeyCredential

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorClient metricsAdvisorClient = new MetricsAdvisorClientBuilder()
    .endpoint("{endpoint}")
    .credential(credential)
    .buildClient();

Criar um cliente de Administração de Métricas usando MetricsAdvisorKeyCredential

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorAdministrationClient metricsAdvisorAdminClient =
    new MetricsAdvisorAdministrationClientBuilder()
        .endpoint("{endpoint}")
        .credential(credential)
        .buildClient();

Criar um cliente do MetricsAdvisor usando o Diretório de Serviços do Azure

O SDK do Azure para Java dá suporte a um pacote de Identidade do Azure, facilitando a obtenção de credenciais de plataforma de identidade da Microsoft.

A autenticação com o AAD requer alguma configuração inicial:

  • Adicionar o pacote de Identidade do Azure
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.7.3</version>
</dependency>

Após a configuração, você pode escolher qual tipo de credencial de azure.identity usar. Por exemplo, DefaultAzureCredential pode ser usado para autenticar o cliente: defina os valores da ID do cliente, da ID do locatário e do segredo do cliente do aplicativo AAD como variáveis de ambiente: AZURE_CLIENT_ID, AZURE_TENANT_ID AZURE_CLIENT_SECRET.

A autorização é mais fácil usando DefaultAzureCredential. Ele encontra a melhor credencial a ser usada em seu ambiente de execução. Para obter mais informações sobre como usar a autorização do Azure Active Directory com o Assistente de Métricas, consulte a documentação associada.

Criar um cliente do Assistente de Métricas usando a autenticação do AAD

TokenCredential credential = new DefaultAzureCredentialBuilder().build();
MetricsAdvisorClient metricsAdvisorClient = new MetricsAdvisorClientBuilder()
    .endpoint("{endpoint}")
    .credential(credential)
    .buildClient();

Criar um cliente de Administração de Métricas usando a autenticação do AAD

TokenCredential credential = new DefaultAzureCredentialBuilder().build();
MetricsAdvisorAdministrationClient metricsAdvisorAdminClient =
    new MetricsAdvisorAdministrationClientBuilder()
        .endpoint("{endpoint}")
        .credential(credential)
        .buildClient();

Principais conceitos

MetricsAdvisorClient

MetricsAdvisorClient ajuda com:

  • Diagnosticar anomalias e incidentes e ajudar na análise da causa raiz de incidentes.
  • Recupere dados de série temporal originais e dados de série temporal enriquecidos pelo serviço.
  • Envie alertas em tempo real por meio de vários ganchos de notificação.
  • Ajuste a detecção de anomalias/incidentes usando comentários para ajustar seu modelo.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient permite que você

  • Gerenciar feeds de dados
  • Listar as métricas disponíveis e suas configurações de detecção
  • Ajustar configurações de detecção de anomalias
  • Configurar configurações de alerta de anomalias
  • Gerenciar ganchos de notificação

Feed de dados

Um feed de dados é o que o Assistente de Métricas ingere da fonte de dados especificada pelo usuário, como fluxo de estrutura do Cosmos, resultado da consulta SQL e assim por diante. Ele contém linhas de carimbos de data/hora, zero ou mais dimensões, uma ou mais Métricas. Portanto, várias métricas podem compartilhar a mesma fonte de dados e até mesmo o mesmo feed de dados.

Métrica do Feed de Dados

Uma métrica é uma medida quantificável usada para acompanhar e avaliar a status de um processo comercial específico. Pode ser uma combinação de vários valores de série temporal divididos por dimensões, por exemplo, contagem de usuários para um mercado vertical da Web e en-us.

Dimensão do Feed de Dados

Uma dimensão é um ou mais valores categóricos do feed de dados fornecido. A combinação desses valores identifica uma série temporal monovariável específica, por exemplo: país, idioma, locatário e assim por diante.

Série de métricas

A série de métricas é uma série de pontos de dados indexados (ou listados ou grafados) na ordem de tempo. Mais comumente, uma série temporal é uma sequência tomada em pontos sucessivos igualmente espaçados no tempo. Portanto, é uma sequência de dados de tempo discreto.

Configuração de detecção de anomalias

Uma configuração de detecção de anomalias é uma configuração fornecida para uma série temporal para identificar se o ponto de dados é detectado como uma anomalia. Uma métrica pode aplicar uma ou mais configurações de detecção. Embora uma configuração de detecção padrão seja aplicada automaticamente a cada métrica (chamada "Padrão"), podemos ajustar os modos de detecção usados em nossos dados criando uma configuração de detecção de anomalias personalizada.

Incidente de anomalias

Incidentes são gerados para série quando ele tem uma anomalia, dependendo das configurações de detecção de anomalias aplicadas. O serviço Assistente de Métricas agrupa uma série de anomalias dentro de uma métrica em um incidente.

Alerta de anomalias

Alertas de anomalias podem ser configurados para serem disparados quando determinadas anomalias são atendidas. Você pode definir vários alertas com configurações diferentes. Por exemplo, você pode criar um anomalyAlert para anomalias com menor impacto nos negócios e outro para alertas mais importantes.

Gancho de notificação

Um gancho de notificação é o ponto de entrada que permite que os usuários assinem alertas em tempo real. Esses alertas são enviados pela Internet usando um Gancho.

Exemplos

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

Este exemplo ingere os dados de fonte de feed de dados especificados SQLServerDataFeedSource pelo usuário para o serviço.

DataFeed dataFeed = new DataFeed()
    .setName("dataFeedName")
    .setSource(new MySqlDataFeedSource("conn-string", "query"))
    .setGranularity(new DataFeedGranularity().setGranularityType(DataFeedGranularityType.DAILY))
    .setSchema(new DataFeedSchema(
        Arrays.asList(
            new DataFeedMetric("cost"),
            new DataFeedMetric("revenue")
        )).setDimensions(
        Arrays.asList(
            new DataFeedDimension("city"),
            new DataFeedDimension("category")
        ))
    )
    .setIngestionSettings(new DataFeedIngestionSettings(OffsetDateTime.parse("2020-01-01T00:00:00Z")))
    .setOptions(new DataFeedOptions()
        .setDescription("data feed description")
        .setRollupSettings(new DataFeedRollupSettings()
            .setRollupType(DataFeedRollupType.AUTO_ROLLUP)));
final DataFeed createdSqlDataFeed = metricsAdvisorAdminClient.createDataFeed(dataFeed);

System.out.printf("Data feed Id : %s%n", createdSqlDataFeed.getId());
System.out.printf("Data feed name : %s%n", createdSqlDataFeed.getName());
System.out.printf("Is the query user is one of data feed administrator : %s%n", createdSqlDataFeed.isAdmin());
System.out.printf("Data feed created time : %s%n", createdSqlDataFeed.getCreatedTime());
System.out.printf("Data feed granularity type : %s%n",
    createdSqlDataFeed.getGranularity().getGranularityType());
System.out.printf("Data feed granularity value : %d%n",
    createdSqlDataFeed.getGranularity().getCustomGranularityValue());
System.out.println("Data feed related metric Ids:");
dataFeed.getMetricIds().forEach((metricId, metricName)
    -> System.out.printf("Metric Id : %s, Metric Name: %s%n", metricId, metricName));
System.out.printf("Data feed source type: %s%n", createdSqlDataFeed.getSourceType());

if (SQL_SERVER_DB == createdSqlDataFeed.getSourceType()) {
    System.out.printf("Data feed sql server query: %s%n",
        ((SqlServerDataFeedSource) createdSqlDataFeed.getSource()).getQuery());
}

Verificar o status da ingestão

Este exemplo verifica o status da ingestão de uma fonte de feed de dados fornecida anteriormente.

String dataFeedId = "3d48er30-6e6e-4391-b78f-b00dfee1e6f5";

metricsAdvisorAdminClient.listDataFeedIngestionStatus(
    dataFeedId,
    new ListDataFeedIngestionOptions(
        OffsetDateTime.parse("2020-01-01T00:00:00Z"),
        OffsetDateTime.parse("2020-09-09T00:00:00Z"))
).forEach(dataFeedIngestionStatus -> {
    System.out.printf("Message : %s%n", dataFeedIngestionStatus.getMessage());
    System.out.printf("Timestamp value : %s%n", dataFeedIngestionStatus.getTimestamp());
    System.out.printf("Status : %s%n", dataFeedIngestionStatus.getStatus());
});

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

Este exemplo demonstra como um usuário pode definir uma configuração de detecção de anomalias para os respectivos dados.

String metricId = "3d48er30-6e6e-4391-b78f-b00dfee1e6f5";

ChangeThresholdCondition changeThresholdCondition = new ChangeThresholdCondition(
    20,
    10,
    true,
    AnomalyDetectorDirection.BOTH,
    new SuppressCondition(1, 2));

HardThresholdCondition hardThresholdCondition = new HardThresholdCondition(
    AnomalyDetectorDirection.DOWN,
    new SuppressCondition(1, 1))
    .setLowerBound(5.0);

SmartDetectionCondition smartDetectionCondition = new SmartDetectionCondition(
    10.0,
    AnomalyDetectorDirection.UP,
    new SuppressCondition(1, 2));

final AnomalyDetectionConfiguration anomalyDetectionConfiguration =
    metricsAdvisorAdminClient.createDetectionConfig(
        metricId,
        new AnomalyDetectionConfiguration("My dataPoint anomaly detection configuration")
            .setDescription("anomaly detection config description")
            .setWholeSeriesDetectionCondition(
                new MetricWholeSeriesDetectionCondition()
                    .setChangeThresholdCondition(changeThresholdCondition)
                    .setHardThresholdCondition(hardThresholdCondition)
                    .setSmartDetectionCondition(smartDetectionCondition)
                    .setConditionOperator(DetectionConditionOperator.OR))
    );

Adicionar ganchos para receber alertas de anomalias

Este exemplo cria um gancho de email que recebe alertas de incidente de anomalias.

NotificationHook emailNotificationHook = new EmailNotificationHook("email Hook")
    .setDescription("my email Hook")
    .setEmailsToAlert(Collections.singletonList("alertme@alertme.com"))
    .setExternalLink("https://adwiki.azurewebsites.net/articles/howto/alerts/create-hooks.html");

final NotificationHook notificationHook = metricsAdvisorAdminClient.createHook(emailNotificationHook);
EmailNotificationHook createdEmailHook = (EmailNotificationHook) notificationHook;
System.out.printf("Email Hook Id: %s%n", createdEmailHook.getId());
System.out.printf("Email Hook name: %s%n", createdEmailHook.getName());
System.out.printf("Email Hook description: %s%n", createdEmailHook.getDescription());
System.out.printf("Email Hook external Link: %s%n", createdEmailHook.getExternalLink());
System.out.printf("Email Hook emails to alert: %s%n",
    String.join(",", createdEmailHook.getEmailsToAlert()));

Configurar uma configuração de alerta de anomalias

Este exemplo demonstra como um usuário pode definir uma configuração de alerta para as anomalias detectadas nos respectivos dados.

String detectionConfigurationId1 = "9ol48er30-6e6e-4391-b78f-b00dfee1e6f5";
String detectionConfigurationId2 = "3e58er30-6e6e-4391-b78f-b00dfee1e6f5";
String hookId1 = "5f48er30-6e6e-4391-b78f-b00dfee1e6f5";
String hookId2 = "8i48er30-6e6e-4391-b78f-b00dfee1e6f5";

final AnomalyAlertConfiguration anomalyAlertConfiguration
    = metricsAdvisorAdminClient.createAlertConfig(
        new AnomalyAlertConfiguration("My anomaly alert config name")
            .setDescription("alert config description")
            .setMetricAlertConfigurations(
                Arrays.asList(
                    new MetricAlertConfiguration(detectionConfigurationId1,
                        MetricAnomalyAlertScope.forWholeSeries()),
                    new MetricAlertConfiguration(detectionConfigurationId2,
                        MetricAnomalyAlertScope.forWholeSeries())
                        .setAlertConditions(new MetricAnomalyAlertConditions()
                            .setSeverityRangeCondition(new SeverityCondition(AnomalySeverity.HIGH,
                                AnomalySeverity.HIGH)))
                ))
            .setCrossMetricsOperator(MetricAlertConfigurationsOperator.AND)
            .setHookIdsToAlert(Arrays.asList(hookId1, hookId2)));

Consultar os resultados da detecção de anomalias

Este exemplo demonstra como um usuário pode consultar alertas disparados para uma configuração de detecção de anomalias e obter anomalias para essa anomaliaAlert.

String alertConfigurationId = "9ol48er30-6e6e-4391-b78f-b00dfee1e6f5";
final OffsetDateTime startTime = OffsetDateTime.parse("2020-01-01T00:00:00Z");
final OffsetDateTime endTime = OffsetDateTime.parse("2020-09-09T00:00:00Z");
metricsAdvisorClient.listAlerts(
    alertConfigurationId,
        startTime, endTime)
    .forEach(alert -> {
        System.out.printf("AnomalyAlert Id: %s%n", alert.getId());
        System.out.printf("AnomalyAlert created on: %s%n", alert.getCreatedTime());

        // List anomalies for returned alerts
        metricsAdvisorClient.listAnomaliesForAlert(
            alertConfigurationId,
            alert.getId())
            .forEach(anomaly -> {
                System.out.printf("DataPoint Anomaly was created on: %s%n", anomaly.getCreatedTime());
                System.out.printf("DataPoint Anomaly severity: %s%n", anomaly.getSeverity().toString());
                System.out.printf("DataPoint Anomaly status: %s%n", anomaly.getStatus());
                System.out.printf("DataPoint Anomaly related series key: %s%n", anomaly.getSeriesKey().asMap());
            });
    });

Solução de problemas

Geral

Os clientes do Assistente de Métricas geram HttpResponseException [exceções][http_response_exception]. Por exemplo, se você tentar fornecer uma ID de comentários não existente, um HttpResponseException será gerado com um erro indicando a causa da falha. No snippet de código a seguir, o erro é tratado normalmente com a captura da exceção e a exibição de informações adicionais sobre o erro.

try {
    metricsAdvisorClient.getFeedback("non_existing_feedback_id");
} catch (HttpResponseException e) {
    System.out.println(e.getMessage());
}

Habilitar o log do cliente

Os SDKs do Azure para Java oferecem uma história de log consistente para ajudar a solucionar problemas de erros do aplicativo e agilizar a resolução. Os logs produzidos capturam o fluxo de um aplicativo antes que acessem o estado do terminal para ajudar a localizar o problema raiz. Exiba o wiki de log para obter diretrizes sobre como habilitar o registro em log.

Cliente HTTP padrão

Por padrão, todas as bibliotecas de cliente usam o cliente HTTP do Netty. Adicionar a dependência acima configurará automaticamente a biblioteca de cliente para usar o cliente HTTP do Netty. A configuração ou a alteração do cliente HTTP é detalhada no wiki de clientes HTTP.

Próximas etapas

Para obter mais detalhes, consulte os exemplos README.

APIs assíncronas

Todos os exemplos mostrados até agora foram usando APIs síncronas, mas também fornecemos suporte completo para APIs assíncronas. Você precisará usar MetricsAdvisorAsyncClient

MetricsAdvisorKeyCredential credential = new MetricsAdvisorKeyCredential("subscription_key", "api_key");
MetricsAdvisorAsyncClient metricsAdvisorAsyncClient = new MetricsAdvisorClientBuilder()
    .credential(credential)
    .endpoint("{endpoint}")
    .buildAsyncClient();

Documentação adicional

Para obter uma documentação mais abrangente sobre o Assistente de Métricas dos Serviços Cognitivos do Azure, consulte a documentação do Assistente de Métricas.

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.

Quando você envia uma solicitação de pull, um bot do CLA determina automaticamente se você precisa fornecer um CLA e preencher a PR corretamente (por exemplo, rótulo, comentário). Basta seguir as instruções fornecidas pelo bot. Você só precisará fazer isso uma vez em todos os repositórios que usam nosso CLA.

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.

Impressões