Biblioteca cliente de Azure Metrics Advisor para Java: versión 1.1.19

Artículo
10/21/2023

Azure Metrics Advisor es un nuevo servicio cognitivo que usa la inteligencia artificial de decisión basada en series temporales para identificar y ayudar a solucionar los incidentes de servicios en línea y supervisar el estado empresarial mediante la automatización del segmento y los dados de datos empresarialesFeedMetrics.

Código | fuentePaquete (Maven) | Documentación | de referencia de API Documentación del | productoMuestras

Introducción

Requisitos previos

Kit de desarrollo de Java (JDK) versión 8 o posterior
Suscripción de Azure
Cuenta de Cognitive Services o Metrics Advisor para usar este paquete.

Inclusión del paquete

Inclusión del archivo BOM

Incluya azure-sdk-bom en el proyecto para depender de la versión de disponibilidad general (GA) de la biblioteca. En el fragmento de código siguiente, reemplace el marcador de posición {bom_version_to_target} por el número de versión. Para más información sobre la lista de materiales, consulte el archivo Léame bom del SDK de 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>

y, a continuación, incluya la dependencia directa en la sección de dependencias sin la etiqueta de versión, como se muestra a continuación.

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

Inclusión de dependencias directas

Si desea depender de una versión determinada de la biblioteca que no está presente en la lista de materiales, agregue la dependencia directa al proyecto como se indica a continuación. Nota: Esta versión tiene como destino la versión 1.0 de la API del servicio Azure Metrics Advisor.

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

Creación de un recurso de Metrics Advisor

Autenticar el cliente

Para interactuar con el servicio Metrics Advisor, deberá crear una instancia del cliente de Metrics Advisor. Los clientes asincrónicos y sincrónicos se pueden crear mediante MetricsAdvisorClientBuilder. La invocación buildClient() creará el cliente sincrónico, mientras que la invocación buildAsyncClient creará su homólogo asincrónico.

Búsqueda del punto de conexión

Puede encontrar el punto de conexión del recurso de Metric Advisor en Azure Portal o la CLI de Azure.

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

Creación de un cliente de MetricsAdvisor mediante MetricsAdvisorKeyCredential

Necesitará dos claves para autenticar al cliente:

Clave de suscripción al recurso de Metrics Advisor. Puede encontrarla en la sección Claves y punto de conexión del recurso en Azure Portal.
La clave de API para la instancia de Metrics Advisor. Puede encontrarlo en el portal web de Metrics Advisor, en claves de API en el menú de navegación izquierdo.

Una vez que tenga las dos claves y el punto de conexión, puede usar la MetricsAdvisorKeyCredential clase para autenticar los clientes de la siguiente manera:

Creación de un cliente de Metrics Advisor mediante MetricsAdvisorKeyCredential

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

Creación de un cliente de Metrics Administration mediante MetricsAdvisorKeyCredential

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

Creación de un cliente de MetricsAdvisor mediante Azure Service Directory

Azure SDK para Java admite un paquete de identidad de Azure, lo que facilita la obtención de credenciales de Plataforma de identidad de Microsoft.

La autenticación con AAD requiere una configuración inicial:

Adición del paquete de identidad de Azure

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.7.3</version>
</dependency>

Registro de una nueva aplicación de Azure Active Directory
Conceda acceso a Metrics Advisor mediante la asignación del "Cognitive Services User" rol a la entidad de servicio.

Después de la instalación, puede elegir el tipo de credencial de azure.identity que se va a usar. Por ejemplo, Se puede usar DefaultAzureCredential para autenticar al cliente: establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

La autorización es más fácil mediante DefaultAzureCredential. Encuentra la mejor credencial para usar en su entorno en ejecución. Para más información sobre el uso de la autorización de Azure Active Directory con Metrics Advisor, consulte la documentación asociada.

Creación de un cliente de Metrics Advisor mediante la autenticación de AAD

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

Creación de un cliente de administración de métricas mediante la autenticación de AAD

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

Conceptos clave

MetricsAdvisorClient

MetricsAdvisorClient ayuda con:

Diagnostique anomalías e incidentes y ayude con el análisis de la causa principal de los incidentes.
Recupere los datos originales de series temporales y los datos de serie temporal enriquecidos por el servicio.
Enviar alertas en tiempo real a través de varios enlaces de notificación.
Ajuste la detección de anomalías o incidentes mediante comentarios para ajustar el modelo.

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient le permite

Administración de fuentes de distribución de datos
Enumerar las métricas disponibles y sus configuraciones de detección
Ajuste de las configuraciones de detección de anomalías
Configuración de configuraciones de alertas de anomalías
Administrar enlaces de notificación

Fuente de distribución de datos

Una fuente de distribución de datos es lo que Metrics Advisor ingiere del origen de datos especificado por el usuario, como el flujo de estructura de Cosmos, el resultado de la consulta SQL, etc. Contiene filas de marcas de tiempo, cero o más dimensiones, una o varias métricas. Por lo tanto, varias métricas podrían compartir el mismo origen de datos e incluso la misma fuente de distribución de datos.

Métrica de fuente de distribución de datos

Una métrica es una medida cuantificable que se usa para realizar un seguimiento y evaluar el estado de un proceso empresarial específico. Puede ser una combinación de varios valores de serie temporal divididos por dimensiones, por ejemplo, recuento de usuarios para un mercado web vertical y en-us.

Dimensión de fuente de distribución de datos

Una dimensión es uno o varios valores categóricos de la fuente de distribución de datos proporcionada. La combinación de esos valores identifica una serie temporal univariante determinada, por ejemplo: país, idioma, inquilino, etc.

Serie de métricas

La serie de métricas es una serie de puntos de datos indexados (o enumerados o grafos) en orden de tiempo. Normalmente, una serie temporal es una secuencia tomada en sucesivos puntos espaciados igualmente en el tiempo. Por lo tanto, es una secuencia de datos en tiempo discreto.

Configuración de detección de anomalías

Una configuración de detección de anomalías es una configuración proporcionada para una serie temporal para identificar si el punto de datos se detecta como anomalía. Una métrica puede aplicar una o varias configuraciones de detección. Aunque una configuración de detección predeterminada se aplica automáticamente a cada métrica (denominada "Valor predeterminado"), podemos ajustar los modos de detección usados en nuestros datos mediante la creación de una configuración de detección de anomalías personalizada.

Incidente de anomalías

Los incidentes se generan para series cuando tiene una anomalía en función de las configuraciones de detección de anomalías aplicadas. El servicio Metrics Advisor agrupa una serie de anomalías dentro de una métrica en un incidente.

Alerta de anomalías

Las alertas de anomalías se pueden configurar para que se desencadene cuando se cumplan ciertas anomalías. Puede establecer varias alertas con distintas configuraciones. Por ejemplo, podría crear una anomalyAlert para anomalías con un menor impacto empresarial y otra para alertas más importantes.

Enlace de notificación

Un enlace de notificación es el punto de entrada que permite a los usuarios suscribirse a alertas en tiempo real. Estas alertas se envían a través de Internet, mediante un enlace.

Ejemplos

Adición de una fuente de distribución de datos desde un origen de datos o de ejemplo
Comprobación del estado de la ingesta
Configuración de la configuración de detección de anomalías
Adición de enlaces para recibir alertas de anomalías
Configuración de una configuración de alerta de anomalías
Consulta de los resultados de la detección de anomalías

Incorporación de una fuente de distribución de datos desde un origen de datos o un ejemplo

En este ejemplo se ingieren los datos del origen de fuente de distribución de datos especificados SQLServerDataFeedSource por el usuario en el servicio.

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());
}

Comprobación del estado de la ingesta

En este ejemplo se comprueba el estado de la ingesta de un origen de una fuente de distribución de datos proporcionado previamente.

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());
});

Configuración de la detección de anomalías

En este ejemplo se muestra la forma en que un usuario puede configurar una configuración de detección de anomalías para sus datos.

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

Adición de enlaces para recibir alertas de anomalías

En este ejemplo se crea un enlace de correo electrónico que recibe alertas de incidentes de anomalías.

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

Configuración de una configuración de alerta de anomalías

En este ejemplo se muestra la forma en que un usuario puede configurar una configuración de alertas para las anomalías detectadas en sus datos.

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

Resultados de la detección de anomalías de las consultas

En este ejemplo se muestra cómo un usuario puede consultar las alertas desencadenadas para una configuración de detección de anomalías y obtener anomalías para esa anomalíaAlert.

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());
            });
    });

Solución de problemas

General

Los clientes de Metrics Advisor generan HttpResponseException [excepciones][http_response_exception]. Por ejemplo, si intenta proporcionar un identificador HttpResponseException de comentarios no existente, se generaría un error que indica la causa del error. En el siguiente fragmento de código, el error se controla correctamente mediante la captura y presentación de la información adicional sobre el error.

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

Habilitación del registro de cliente

Los SDK de Azure para Java ofrecen una historia de registro coherente para ayudar a solucionar errores de aplicación y acelerar su resolución. Los registros generados capturarán el flujo de una aplicación antes de alcanzar el estado terminal para ayudar a encontrar el problema raíz. Consulte la wiki de registro para obtener instrucciones sobre cómo habilitar el registro.

Cliente HTTP predeterminado

Todas las bibliotecas cliente usan de forma predeterminada el cliente HTTP de Netty. Al agregar la dependencia anterior, se configurará automáticamente la biblioteca cliente para usar el cliente HTTP de Netty. La configuración o el cambio del cliente HTTP se detalla en la wiki de clientes HTTP.

Pasos siguientes

Para obtener más información, consulte el archivo Léame de ejemplos.

API asincrónicas

Todos los ejemplos que se muestran hasta ahora han estado usando API sincrónicas, pero también proporcionamos compatibilidad completa con las API asincrónicas. Deberá usar MetricsAdvisorAsyncClient

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

Documentación adicional

Para obtener documentación más amplia sobre Metrics Advisor de Azure Cognitive Services, consulte la documentación de Metrics Advisor.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Impresiones

Compartir a través de