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

适用于 Java 的 Azure Monitor 引入客户端库 - 版本 1.1.1

  • 项目

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

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

入门

先决条件

添加包

包括 BOM 文件

请将 包含在 azure-sdk-bom 项目中，以依赖于库的最新稳定版本。 在以下代码片段中，将 {bom_version_to_target} 占位符替换为版本号。 若要详细了解 BOM，请参阅 AZURE SDK BOM 自述文件。

<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 节中包含直接依赖项，不带版本标记，如下所示。

<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。 该库包括客户端的同步和异步形式。 若要进行身份验证，以下示例使用 DefaultAzureCredentialBuilderazure-identity 包中的 。

使用 Azure Active Directory 进行身份验证

可以使用 Azure 标识库通过 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();

关键概念

数据收集终结点

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

数据收集规则

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

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

有关详细信息，请参阅 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 方法提供一个选项，用于通过错误处理程序处理单个服务错误，如以下示例所示。 此错误处理程序包括异常详细信息和未能上传的所有日志的列表。 如果未提供错误处理程序，则 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)，并声明你有权（并且确实有权）授予我们使用你的贡献的权利。 有关详细信息，请访问 https://cla.microsoft.com 。

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

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

曝光数