Azure.Monitor.Ingestion 1.1.2

.NET 的 Azure Monitor Ingestion 客户端库

Azure Monitor Ingestion 客户端库用于将自定义日志发送到 Azure Monitor。

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

资源

• 源代码
• NuGet 包
• 服务文档
• 变更日志

入门

先决条件

• 一个Azure 订阅
• 一个 TokenCredential 实现，例如一个 Azure Identity 库凭证类型。
• 一个 数据收集端点
• 一个 数据收集规则
• 一个 日志分析工作空间

安装包

使用 NuGet 安装 .NET Azure Monitor Ingestion 客户端库

dotnet add package Azure.Monitor.Ingestion

认证客户端

要导入数据，需要认证的客户端。为了认证，创建一个 TokenCredential 类的实例，并将其传递给 LogsIngestionClient 类的构造函数。

为了认证，以下示例使用 Azure.Identity 包中的 DefaultAzureCredential

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var client = new LogsIngestionClient(endpoint, credential);

为客户配置 Azure 主权云

默认情况下，LogsIngestionClient 配置为连接到 Azure 公有云。若要连接到主权云，设置 LogsIngestionClientOptions.Audience 属性。例如

var endpoint = new Uri("<data_collection_endpoint_uri>");
var credential = new DefaultAzureCredential();
var clientOptions = new LogsIngestionClientOptions
{
    Audience = LogsIngestionAudience.AzureChina
};
var client = new LogsIngestionClient(endpoint, credential, clientOptions);

上传日志

有关日志导入的示例，请参阅示例部分。

关键概念

数据收集端点

数据收集端点（DCE）允许您为 Azure Monitor 唯一地配置导入设置。该文章提供了 DCE 的概述，包括其内容、结构和如何创建和操作它们。

数据收集规则

数据收集规则（DCR）定义了 Azure Monitor 收集的数据，并指定了这些数据应如何以及在哪里发送或存储。必须指定一个 DCR 才能使用 REST API 调用。单个 DCE 可支持多个 DCR，因此您可以为不同的来源和目标表指定不同的 DCR。

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

有关更多信息，请参阅Azure Monitor 的数据收集规则。

日志分析工作空间表

自定义日志可以将数据发送到您创建的任何自定义表以及 Log Analytics 工作空间中的某些内置表。在向其发送数据之前，目标表必须存在。以下是目前支持的内置表：

• CommonSecurityLog
• SecurityEvent
• Syslog
• WindowsEvent

线程安全

我们保证所有客户端实例方法都是线程安全的，并且彼此独立（准则）。此设计确保即使在多线程情况下，重用客户端实例的建议始终是安全的。

其他概念

客户端选项 | 访问响应 | 长时间运行的操作 | 处理失败 | 诊断 | 模拟 | 客户端生命周期

示例

• 使用依赖注入注册客户端
• 上传自定义日志
• 以 IEnumerable 的形式上传自定义日志
• 使用 EventHandler 上传自定义日志的 IEnumerable 形式
• 验证日志

您可以使用 示例 来熟悉不同的 API。

使用依赖注入注册客户端

要将 LogsIngestionClient 与依赖注入 (DI) 容器注册，请调用 AddLogsIngestionClient 方法。有关更多信息，请参阅 注册客户端。

上传自定义日志

您可以使用 LogsIngestionClient.Upload 或 LogsIngestionClient.UploadAsync 方法上传日志。注意数据摄入限制。此方法有一个可选参数：字符串内容编码。这指的是传入的请求内容的编码。如果您正在传入已修改的内容，请设置内容编码参数。例如，如果您的内容已压缩，请将内容编码设置为“gzip”。如果没有设置此参数，则默认行为是对所有输入进行gzip压缩。

var endpoint = new Uri("<data_collection_endpoint>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);
DateTimeOffset currentTime = DateTimeOffset.UtcNow;

// Use BinaryData to serialize instances of an anonymous type into JSON
BinaryData data = BinaryData.FromObjectAsJson(
    new[] {
        new
        {
            Time = currentTime,
            Computer = "Computer1",
            AdditionalContext = new
            {
                InstanceName = "user1",
                TimeZone = "Pacific Time",
                Level = 4,
                CounterName = "AppMetric1",
                CounterValue = 15.3
            }
        },
        new
        {
            Time = currentTime,
            Computer = "Computer2",
            AdditionalContext = new
            {
                InstanceName = "user2",
                TimeZone = "Central Time",
                Level = 3,
                CounterName = "AppMetric1",
                CounterValue = 23.5
            }
        },
    });

// Upload our logs
Response response = await client.UploadAsync(
    ruleId,
    streamName,
    RequestContent.Create(data)).ConfigureAwait(false);

以 IEnumerable 的形式上传自定义日志

您还可以使用 LogsIngestionClient.Upload 或 LogsIngestionClient.UploadAsync 方法上传日志，其中日志通过泛型 IEnumerable 类型传入，并可选地包含 LogsUploadOptions 参数。LogsUploadOptions 参数包括序列化器、并发性和 EventHandler。

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries).ConfigureAwait(false);

使用 EventHandler 上传自定义日志的 IEnumerable 形式

您也可以使用 LogsIngestionClient.Upload 或 LogsIngestionClient.UploadAsync 方法上传日志，这两种方法中，日志通过泛型 IEnumerable 类型传入。此外，还有一个类型为 LogsUploadOptions 的参数，可以设置序列化器、并发性和 EventHandler。默认序列化器设置为 System.Text.Json，但您可以传入您希望使用的序列化器。MaxConcurrency 属性设置在 UploadAsync 方法中将使用的线程数。默认值为 5，并且此参数在 Upload 方法中未使用。EventHandler 用于错误处理。它允许用户在批处理失败时中止上传，并访问已失败的日志和相应的异常。如果没有 EventHandler，上传失败将抛出 AggregateException。

var endpoint = new Uri("<data_collection_endpoint_uri>");
var ruleId = "<data_collection_rule_id>";
var streamName = "<stream_name>";

var credential = new DefaultAzureCredential();
LogsIngestionClient client = new(endpoint, credential);

DateTimeOffset currentTime = DateTimeOffset.UtcNow;

var entries = new List<Object>();
for (int i = 0; i < 100; i++)
{
    entries.Add(
        new {
            Time = currentTime,
            Computer = "Computer" + i.ToString(),
            AdditionalContext = i
        }
    );
}
// Set concurrency and EventHandler in LogsUploadOptions
LogsUploadOptions options = new LogsUploadOptions();
options.MaxConcurrency = 10;
options.UploadFailed += Options_UploadFailed;

// Upload our logs
Response response = await client.UploadAsync(ruleId, streamName, entries, options).ConfigureAwait(false);

Task Options_UploadFailed(LogsUploadFailedEventArgs e)
{
    // Throw exception from EventHandler to stop Upload if there is a failure
    IReadOnlyList<object> failedLogs = e.FailedLogs;
    // 413 status is RequestTooLarge - don't throw here because other batches can successfully upload
    if ((e.Exception is RequestFailedException) && (((RequestFailedException)e.Exception).Status != 413))
        throw e.Exception;
    else
        return Task.CompletedTask;
}

验证日志

您可以通过使用 Azure Monitor Query 库来验证您的数据是否已正确上传。在验证日志之前，请首先运行 上传自定义日志 示例。

var workspaceId = "<log_analytics_workspace_id>";
var tableName = "<table_name>";

var credential = new DefaultAzureCredential();
LogsQueryClient logsQueryClient = new(credential);

LogsBatchQuery batch = new();
string query = tableName + " | Count;";
string countQueryId = batch.AddWorkspaceQuery(
    workspaceId,
    query,
    new QueryTimeRange(TimeSpan.FromDays(1)));

Response<LogsBatchQueryResultCollection> queryResponse =
    await logsQueryClient.QueryBatchAsync(batch).ConfigureAwait(false);

Console.WriteLine("Table entry count: " +
    queryResponse.Value.GetResult<int>(countQueryId).Single());

故障排除

有关各种失败场景的诊断细节，请参阅我们的 故障排除指南。

下一步

要了解有关 Azure Monitor 的更多信息，请参阅 Azure Monitor 服务文档。

贡献

本项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议 (CLA)，声明您有授权并且确实授予我们使用您贡献的权利。有关详情，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA 机器人将自动判断您是否需要提供 CLA，并相应地标记 PR。例如，标签和注释。请按照机器人提供的说明操作。您只需在整个我们的 CLA 中签署一次 CLA。

本项目已采用微软开源行为准则。如需更多信息，请参阅行为准则常见问题解答或联系[email protected]进行咨询或留言。