Java 用 Azure Monitor インジェスト クライアント ライブラリ - バージョン 1.1.1

  • [アーティクル]

Azure Monitor インジェスト クライアント ライブラリは、Logs Ingestion API を使用してカスタム ログを Azure Monitor に送信するために使用されます。

このライブラリを使用すると、実質的に任意のソースから、サポートされている組み込みテーブル、または Log Analytics ワークスペースで作成したカスタム テーブルにデータを送信できます。 カスタム列を使用して組み込みテーブルのスキーマを拡張することもできます。

作業の開始

前提条件

パッケージを組み込む

BOM ファイルを含める

最新の安定バージョンの 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-monitor-ingestion</artifactId>
  </dependency>
</dependencies>

直接依存関係を含める

BOM に存在しない特定のバージョンのライブラリに依存する場合は、次のように直接依存関係をプロジェクトに追加します。

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-monitor-ingestion</artifactId>
    <version>1.1.1</version>
</dependency>

クライアントを作成する

Azure Monitor にログをアップロードするには、認証されたクライアントが必要です。 ライブラリには、クライアントの同期形式と非同期形式の両方が含まれています。 認証を行うために、次の例では azure-identity パッケージから を使用DefaultAzureCredentialBuilderします。

Azure Active Directory を使用した認証

Azure Id ライブラリを使用して、Azure Active Directory で認証できます。 次に示す DefaultAzureCredential プロバイダー、または Azure SDK で提供されている他の資格情報プロバイダーを使用するには、パッケージを azure-identity 含めてください。

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

AAD アプリケーションのクライアント ID、テナント ID、クライアント シークレットの値を環境変数として設定します(AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET)。

同期ログ インジェスト クライアント

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildClient();

非同期ログ インジェスト クライアント

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionAsyncClient asyncClient = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint>")
        .credential(tokenCredential)
        .buildAsyncClient();

主要な概念

データ収集エンドポイント

データ収集エンドポイント (DCE) を使用すると、Azure Monitor のデータ収集エンドポイントのインジェスト設定を一意に構成できます。 この記事 では、データ収集エンドポイントの内容と構造、およびそれらを作成して操作する方法など、データ収集エンドポイントの概要について説明します。

データ収集ルール

データ収集規則 (DCR) は、Azure Monitor によって収集されるデータを定義し、そのデータの送受信方法と場所を指定します。 REST API 呼び出しでは、使用する DCR を指定する必要があります。 1 つの DCE で複数の DCR をサポートできます。そのため、ソース テーブルとターゲット テーブルごとに異なる DCR を指定できます。

DCR は、入力データの構造とターゲット テーブルの構造を理解する必要があります。 この 2 つが一致しない場合は、変換を使用してソース データを変換し、ターゲット テーブルと一致させることができます。 変換を使用して、ソース データをフィルター処理し、その他の計算や変換を実行することもできます。

詳細については、「 Azure Monitor でのデータ収集ルール」を参照してください。 DCR ID を取得する方法については、 このチュートリアルを参照してください。

Log Analytics ワークスペース テーブル

カスタム ログは、作成した任意のカスタム テーブルと Log Analytics ワークスペース内の特定の組み込みテーブルにデータを送信できます。 ターゲット テーブルは、データを送信する前に存在している必要があります。 現在サポートされている組み込みのテーブルは次のとおりです。

ログの取得

このライブラリを使用してアップロードされたログは、 Azure Monitor クエリ クライアント ライブラリを使用して照会できます。

例

カスタム ログをアップロードする

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
client.upload("<data-collection-rule-id>", "<stream-name>", logs);
System.out.println("Logs uploaded successfully");

最大コンカレンシーを使用してカスタム ログをアップロードする

入力ログの コレクション内の が大きすぎる場合、クライアントは入力を複数の小さな要求に分割します。 これらの要求は、既定では順次送信されますが、 で LogsUploadOptions最大コンカレンシーを構成することで、次の例に示すように、これらの要求をサービスに同時に送信できます。

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();
LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setMaxConcurrency(3);
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);
System.out.println("Logs uploaded successfully");

エラー処理を使用してカスタム ログをアップロードする

ログの大規模なコレクションをアップロードする場合、クライアントは入力を複数の小さなサービス要求に分割します。 upload メソッドには、次の例に示すように、エラー ハンドラーを使用して個々のサービス エラーを処理するオプションが用意されています。 このエラー ハンドラーには、例外の詳細と、アップロードに失敗したすべてのログの一覧が含まれます。 エラー ハンドラーが指定されていない場合、アップロード メソッドは、すべてのサービス エラーを含む集計例外をスローします。

DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();

LogsIngestionClient client = new LogsIngestionClientBuilder()
        .endpoint("<data-collection-endpoint")
        .credential(tokenCredential)
        .buildClient();

List<Object> logs = getLogs();

LogsUploadOptions logsUploadOptions = new LogsUploadOptions()
        .setLogsUploadErrorConsumer(uploadLogsError -> {
            System.out.println("Error message " + uploadLogsError.getResponseException().getMessage());
            System.out.println("Total logs failed to upload = " + uploadLogsError.getFailedLogs().size());

            // throw the exception here to abort uploading remaining logs
            // throw uploadLogsError.getResponseException();
        });
client.upload("<data-collection-rule-id>", "<stream-name>", logs, logsUploadOptions,
        Context.NONE);

トラブルシューティング

さまざまな障害シナリオの診断の詳細については、 トラブルシューティング ガイドを参照してください。

次の手順

その他のサンプル については、こちらを参照してください。

共同作成

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

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

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

インプレッション数