你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Python 的 Azure Monitor 引入客户端库 - 版本 1.0.3

项目
11/09/2023

Azure Monitor 引入客户端库用于使用日志引入 API 将自定义日志发送到 Azure Monitor。

此库允许将几乎任何源中的数据发送到支持的内置表或 Log Analytics 工作区中创建的自定义表。甚至可以使用自定义列来扩展内置表的架构。

资源：

入门

先决条件

安装包

使用 pip 安装适用于 Python 的 Azure Monitor 引入客户端库：

pip install azure-monitor-ingestion

创建客户端

需要经过身份验证的客户端才能将日志上传到 Azure Monitor。库包括客户端的同步和异步形式。若要进行身份验证，请创建令牌凭据的实例。创建 LogsIngestionClient时使用该实例。以下示例使用 DefaultAzureCredentialazure-identity 包中的。

同步客户端

请考虑以下示例，该示例创建用于上传日志的同步客户端：

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 云，需要一些额外的配置。必须使用关键字 (keyword) 参数提供credential_scopes适当的身份验证范围。以下示例演示如何将客户端配置为连接到 Azure 美国政府：

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

关键概念

数据收集终结点

数据收集端点允许你唯一地配置 Azure Monitor 的引入设置。本文概述了数据收集终结点，包括其内容和结构，以及如何创建和使用它们。

数据收集规则

数据收集规则 (DCR) 定义 Azure Monitor 收集的数据，并指定发送或存储这些数据的方式和位置。 REST API 调用必须指定要使用的 DCR。一个 DCE 可以支持多个 DCR，因此，可以为不同的源和目标表指定不同的 DCR。

DCR 必须了解输入数据的结构和目标表的结构。如果这两个结构不匹配，它可以使用转换将源数据转换为与目标表匹配。你还可使用转换来筛选源数据并执行任何其他计算或转换。

有关详细信息，请参阅 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_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 Monitor，请参阅 Azure Monitor 服务文档。

示例

以下代码示例演示 Azure Monitor 引入客户端库的常见方案。

日志引入示例

贡献

本项目欢迎贡献和建议。大多数贡献要求你同意贡献者许可协议 (CLA)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。有关详细信息，请访问 cla.microsoft.com。

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 在所有存储库中执行此操作一次。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答；若有其他任何问题或意见，请联系 opencode@microsoft.com。