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

  • [アーティクル]

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

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

リソース:

作業の開始

前提条件

パッケージをインストールする

pip を使用して Python 用 Azure Monitor インジェスト クライアント ライブラリをインストールします。

pip install azure-monitor-ingestion

クライアントを作成する

Azure Monitor にログをアップロードするには、認証されたクライアントが必要です。 ライブラリには、クライアントの同期形式と非同期形式の両方が含まれています。 認証するには、トークン資格情報のインスタンスを作成します。 を作成するときに、そのインスタンスを LogsIngestionClient使用します。 次の例では、azure-identity パッケージから を使用DefaultAzureCredentialします。

同期クライアント

ログをアップロードするための同期クライアントを作成する次の例を考えてみましょう。

import os
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

非同期クライアント

クライアント API の非同期形式は、サフィックス付き名前空間にあります .aio。 次に例を示します。

import os
from azure.identity.aio import DefaultAzureCredential
from azure.monitor.ingestion.aio import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()
logs_client = LogsIngestionClient(endpoint, credential)

非パブリック Azure クラウドのクライアントを構成する

既定では、 LogsIngestionClient はパブリック Azure クラウドに接続するように構成されています。 非パブリック Azure クラウドに接続するには、いくつかの追加構成が必要です。 認証の適切なスコープは、キーワード (keyword)引数を使用して指定するcredential_scopes必要があります。 次の例は、Azure US Government に接続するようにクライアントを構成する方法を示しています。

logs_client = LogsIngestionClient(endpoint, credential_scopes=["https://monitor.azure.us//.default"])

主要な概念

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

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

データ収集ルール

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

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

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

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

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

ログの取得

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

例

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

この例では、Azure Monitor へのログのアップロードを示します。

import os

from azure.core.exceptions import HttpResponseError
from azure.identity import DefaultAzureCredential
from azure.monitor.ingestion import LogsIngestionClient

endpoint = os.environ['DATA_COLLECTION_ENDPOINT']
credential = DefaultAzureCredential()

client = LogsIngestionClient(endpoint=endpoint, credential=credential, logging_enable=True)

rule_id = os.environ['LOGS_DCR_RULE_ID']
body = [
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer1",
        "AdditionalContext": "context-2"
      },
      {
        "Time": "2021-12-08T23:51:14.1104269Z",
        "Computer": "Computer2",
        "AdditionalContext": "context"
      }
    ]

try:
    client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body)
except HttpResponseError as e:
    print(f"Upload failed: {e}")

カスタム エラー処理を使用したアップロード

カスタム エラー処理を使用してログをアップロードするには、 メソッドの パラメーターにコールバック関数をon_errorupload渡します。 コールバック関数は、アップロード中に発生する各エラーに対して呼び出され、オブジェクトに対応する 1 つの引数が LogsUploadError 必要です。 このオブジェクトには、発生したエラーと、アップロードに失敗したログの一覧が含まれています。

# Example 1: Collect all logs that failed to upload.
failed_logs = []
def on_error(error):
    print("Log chunk failed to upload with error: ", error.error)
    failed_logs.extend(error.failed_logs)

# Example 2: Ignore all errors.
def on_error_pass(error):
    pass

client.upload(rule_id=rule_id, stream_name=os.environ['LOGS_DCR_STREAM_NAME'], logs=body, on_error=on_error)

トラブルシューティング

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

次のステップ

Azure Monitor の詳細については、 Azure Monitor サービスのドキュメントを参照してください。

サンプル

次のコード サンプルは、Azure Monitor インジェスト クライアント ライブラリの一般的なシナリオを示しています。

ログ インジェストのサンプル

共同作成

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

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

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