適用于 Python 的 Azure 監視器擷取用戶端程式庫 - 1.0.3 版

發行項
11/09/2023

Azure 監視器擷取用戶端程式庫可用來使用記錄擷取 API將自訂記錄傳送至Azure 監視器。

此程式庫可讓您將資料從幾乎任何來源傳送到支援的內建資料表，或傳送至您在 Log Analytics 工作區中建立的自訂資料表。您甚至還可以使用自訂資料行擴充內建資料表的結構描述。

資源：

開始使用

Prerequisites

安裝套件

使用 pip安裝適用于 Python 的 Azure 監視器擷取用戶端程式庫：

pip install azure-monitor-ingestion

建立用戶端

需要已驗證的用戶端，才能將記錄上傳至 Azure 監視器。程式庫同時包含用戶端的同步和非同步形式。若要進行驗證，請建立權杖認證的實例。建立 LogsIngestionClient 時，請使用該實例。下列範例會從azure 身分識別套件使用 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 的非同步形式可在 -suffixed 命名空間中找到 .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 雲端，需要一些額外的設定。必須使用關鍵字引數來提供 credential_scopes 適當的驗證範圍。下列範例示範如何設定用戶端以連線到 Azure 美國政府：

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

重要概念

資料收集端點

資料收集端點 (DCE) 可讓您設定獨特的 Azure 監視器擷取設定。本文提供資料收集端點的概觀，包括其內容和結構，以及如何建立及使用這些端點。

資料收集規則

資料收集規則 (DCR) 定義 Azure 監視器收集的資料，並指定該資料應該傳送或儲存的方式和位置。 REST API 呼叫必須指定要使用的 DCR。單一 DCE 可以支援多個 DCR，因此您可以針對不同的來源和目標資料表指定不同的 DCR。

DCR 必須了解輸入資料和目標資料表的結構。如果兩者不相符，其可以使用轉換，以此來轉換來源資料，使其符合目標資料表。您也可以使用轉換來篩選來源資料，並執行任何其他的計算或轉換。

如需詳細資訊，請參閱 Azure 監視器中的資料收集規則，如需 DCR 結構的詳細資訊，請參閱這篇文章。如需如何擷取 DCR 識別碼的資訊，請參閱本教學課程。

Log Analytics 工作區資料表

自訂記錄可將資料傳送至您建立的任何自訂資料表，以及您 Log Analytics 工作區中的某些內建資料表。目標資料表必須先存在，您才能將資料傳送至該資料表。目前下列的內建資料表受到支援：

記錄擷

您可以使用 Azure 監視器查詢用戶端程式庫來查詢使用此程式庫上傳的記錄。

上傳自訂記錄

此範例顯示將記錄上傳至 Azure 監視器。

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_error 方法的參數 upload 。針對上傳期間發生的每個錯誤呼叫回呼函式，而且應該預期有一個對應至 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 監視器，請參閱 Azure 監視器服務檔。

範例

下列程式碼範例示範 Azure 監視器擷取用戶端程式庫的常見案例。

記錄擷取範例

參與

此專案歡迎參與和提供建議。大部分的參與都要求您同意「參與者授權合約 (CLA)」，宣告您有權且確實授與我們使用投稿的權利。如需詳細資訊，請造訪 cla.microsoft.com。

當您提交提取要求時，CLA Bot 會自動判斷您是否需要提供 CLA，並適當地裝飾 PR (例如標籤、註解)。請遵循 bot 提供的指示。您只需要使用 CLA 在所有存放庫上執行此動作一次。

此專案採用了 Microsoft 開放原始碼管理辦法。如需詳細資訊，請參閱管理辦法常見問題集，如有其他問題或意見，請連絡 opencode@microsoft.com。

共用方式為