Java 用 Azure Metrics Advisor クライアントライブラリ - バージョン 1.1.19

[アーティクル]
10/21/2023

Azure Metrics Advisor は、時系列ベースの意思決定 AI を使用して、オンラインサービスのインシデントの特定とトラブルシューティングを支援し、ビジネスデータFeedMetricsのスライスとサイコロを自動化してビジネスの正常性を監視する新しい Cognitive Service です。

ソースコード | パッケージ (Maven) | API リファレンスドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

Java Development Kit (JDK) バージョン 8 以降
Azure サブスクリプション
このパッケージを使用する Cognitive Services または Metrics Advisor アカウント。

パッケージを組み込む

BOM ファイルを含める

ライブラリの一般提供 (GA) バージョンに依存するには、azure-sdk-bom をプロジェクトに含めてください。次のスニペットでは、{bom_version_to_target} プレースホルダーをバージョン番号に置き換えます。 BOM の詳細については、 AZURE SDK BOM README に関するページを参照してください。

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

次に、次に示すようにバージョンタグを使用せずに、依存関係セクションに直接依存関係を含めます。

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

直接依存関係を含める

BOM に存在しないライブラリの特定のバージョンに依存する場合は、次のように直接依存関係をプロジェクトに追加します。 メモ： このバージョンは、Azure Metrics Advisor サービス API バージョン v1.0 を対象とします。

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

Metrics Advisor リソースを作成する

クライアントを認証する

Metrics Advisor サービスと対話するには、Metrics Advisor クライアントのインスタンスを作成する必要があります。非同期クライアントと同期クライアントは、を使用 MetricsAdvisorClientBuilderして作成できます。を buildClient() 呼び出すと同期クライアントが作成され、を buildAsyncClient 呼び出すと非同期クライアントが作成されます。

エンドポイントの参照

メトリックアドバイザーリソースの エンドポイント は、 Azure Portal または Azure CLI で確認できます。

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

MetricsAdvisorKeyCredential を使用して MetricsAdvisor クライアントを作成する

クライアントを認証するには、次の 2 つのキーが必要です。

Metrics Advisor リソースのサブスクリプションキー。これは、Azure portal 内の自分のリソースの [キーとエンドポイント] セクションで確認できます。
自分の Metrics Advisor インスタンスの API キー。これは、Metrics Advisor の Web ポータルの左側のナビゲーションメニューの API キーで確認できます。

2 つのキーとエンドポイントを取得したら、クラスを MetricsAdvisorKeyCredential 使用して、次のようにクライアントを認証できます。

MetricsAdvisorKeyCredential を使用して Metrics Advisor クライアントを作成する

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

MetricsAdvisorKeyCredential を使用して Metrics Administration クライアントを作成する

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

Azure Service Directory を使用して MetricsAdvisor クライアントを作成する

Azure SDK for Java では Azure Identity パッケージがサポートされているため、Microsoft ID プラットフォームから資格情報を簡単に取得できます。

AAD を使用した認証には、いくつかの初期セットアップが必要です。

Azure Identity パッケージを追加する

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

新しい Azure Active Directory アプリケーションを登録する
サービスプリンシパルにロールを割り当てることで、"Cognitive Services User"Metrics Advisor へのアクセス権を付与します。

セットアップ後、使用する azure.identity から資格情報の種類を選択できます。たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。AAD アプリケーションのクライアント ID、テナント ID、クライアントシークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET)。

承認は、 DefaultAzureCredential を使用するのが最も簡単です。実行中の環境で使用するのに最適な資格情報が見つかります。 Metrics Advisor で Azure Active Directory 承認を使用する方法の詳細については、関連するドキュメントを参照してください。

AAD 認証を使用して Metrics Advisor クライアントを作成する

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

AAD 認証を使用してメトリック管理クライアントを作成する

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

主要な概念

MetricsAdvisorClient

MetricsAdvisorClient は次の場合に役立ちます。

異常とインシデントを診断し、インシデントの根本原因分析に役立ちます。
サービスによって強化された元の時系列データと時系列データを取得します。
複数の通知フックを介してリアルタイムアラートを送信します。
フィードバックを使用して異常/インシデント検出を調整し、モデルを調整します。

MetricsAdvisorAdministrationClient

MetricsAdvisorAdministrationClient を使用すると、次の操作を行います。

データフィードを管理する
使用可能なメトリックとその検出構成を一覧表示する
異常検出の構成を微調整する
異常アラート構成を構成する
通知フックを管理する

データフィード

データフィードとは、Cosmos 構造体ストリーム、SQL クエリの結果など、ユーザー指定のデータソースから Metrics Advisor が取り込むものです。これには、タイムスタンプの行、0 個以上のディメンション、1 つ以上のメトリックが含まれます。そのため、複数のメトリックが同じデータソースと同じデータフィードを共有する可能性があります。

データフィードメトリック

メトリックは、特定のビジネスプロセスの状態を追跡および評価するために使用される定量化可能なメジャーです。これは、複数の時系列値をディメンションで割った組み合わせにすることができます。たとえば、Web 垂直および en-us 市場のユーザー数などです。

データフィードディメンション

ディメンションは、指定されたデータフィードの 1 つ以上のカテゴリ値です。これらの値を組み合わせることによって、国、言語、テナントなど、特定の一変量時系列が識別されます。

メトリック系列

メトリック系列は、時間順にインデックス付け (または一覧表示またはグラフ化) された一連のデータポイントです。最も一般的な時系列は、連続する等間隔の時点で取得されるシーケンスです。したがって、不連続時間データのシーケンスです。

異常検出の構成

異常検出構成は、データポイントが異常として検出されたかどうかを識別するために時系列に提供される構成です。メトリックに 1 つ以上の検出構成を適用できます。既定の検出構成は各メトリック ("Default" という名前) に自動的に適用されますが、カスタマイズされた異常検出構成を作成することで、データで使用される検出モードを調整できます。

異常インシデント

インシデントは、適用された異常検出構成に応じて異常がある場合にシリーズに対して生成されます。 Metrics Advisor サービスは、メトリック内の一連の異常をインシデントにグループ化します。

異常アラート

異常アラートは、特定の異常が満たされたときにトリガーされるように構成できます。異なる設定で複数のアラートを設定できます。たとえば、ビジネスへの影響が小さい異常に対しては anomalyAlert を作成し、さらに重要なアラートにはもう 1 つを作成できます。

通知フック

通知フックは、ユーザーがリアルタイムアラートをサブスクライブできるようにするエントリポイントです。これらのアラートは、フックを使用してインターネット経由で送信されます。

サンプルまたはデータソースからデータフィードを追加する

この例では、ユーザー指定 SQLServerDataFeedSource のデータフィードソースデータをサービスに取り込みます。

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

インジェストの状態を確認する

この例では、以前に提供されたデータフィードソースのインジェストの状態を確認します。

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

異常検出を構成する

この例では、データの異常検出構成を設定する方法を示します。

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

異常アラートを受信するためのフックを追加する

この例では、異常インシデントアラートを受け取る email hook を作成します。

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

異常アラート構成を構成する

この例では、データ内で検出された異常に対するアラート構成を設定する方法を示します。

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

異常検出の結果を照会する

この例では、ユーザーが異常検出構成に対してトリガーされたアラートに対してクエリを実行し、その anomalyAlert の異常を取得する方法を示します。

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

トラブルシューティング

全般

Metrics Advisor クライアントは HttpResponseException [例外][http_response_exception] を発生させます。たとえば、既存ではないフィードバック ID を HttpResponseException 指定しようとすると、が発生し、エラーの原因を示すエラーが発生します。次のコードスニペットでは、例外をキャッチし、エラーに関する追加情報を表示することで、エラーが適切に処理されます。

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

クライアントのログ記録を有効にする

Azure SDK for Java には、アプリケーションエラーのトラブルシューティングと解決の迅速化に役立つ一貫したログ記録のストーリーが用意されています。生成されたログでは、最終状態に達する前のアプリケーションのフローがキャプチャされ、根本原因を特定するのに役立ちます。ログ記録の有効化に関するガイダンスについては、ログ Wiki を参照してください。

既定の HTTP クライアント

すべてのクライアントライブラリでは、Netty HTTP クライアントが既定で使用されます。前述の依存関係を追加すると、Netty HTTP クライアントを使用するようにクライアントライブラリが自動的に構成されます。 HTTP クライアントの構成と変更については、HTTP クライアントの Wiki で詳しく説明されています。

次の手順

詳細については、 README のサンプルを参照してください。

非同期 API

これまでに示した例はすべて同期 API を使用していますが、非同期 API の完全なサポートも提供しています。を使用する必要があります MetricsAdvisorAsyncClient

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

その他のドキュメント

Azure Cognitive Services Metrics Advisor の詳細なドキュメントについては、 Metrics Advisor のドキュメントを参照してください。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。ボットによって提供される手順にそのまま従ってください。この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープンソースの倫理規定を採用しています。詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。

インプレッション数

次の方法で共有

Java 用 Azure Metrics Advisor クライアント ライブラリ - バージョン 1.1.19