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

使用适用于 .NET 的客户端库进行客户端日志记录

项目
06/27/2023

使用适用于 .NET 的 Azure 存储客户端库 (版本 2.1 及更高版本) ，可以使用标准 .NET 诊断基础结构从 .NET 客户端应用程序中记录 Azure 存储请求。这样，可以查看客户端发送到 Azure 存储服务的请求及其接收的响应的详细信息。

使用 Azure 存储客户端库可以控制可以记录哪些存储请求，而 .NET 诊断基础结构可让你完全控制日志数据，例如发送数据的位置。例如，可以选择将日志数据发送到文件或应用程序进行处理。结合 Azure 存储分析和网络监视，可以使用客户端库日志记录来详细描述应用程序如何与 Azure 存储服务交互。有关详细信息，请参阅监视、诊断和排查 Azure 存储问题。

如何启用客户端库日志记录

以下示例显示收集存储日志消息并将其永久保存到文本文件所需的 system.diagnostics 配置。配置节可以添加到 app.config 或 web.config 文件。

注意

如果使用的版本早于 10.0.0，请使用名称 Microsoft.WindowsAzure.Storage 而不是 Microsoft.Azure.Storage。

<system.diagnostics>  
     <!--In a dev/test environment you can set autoflush to true in order to autoflush to the log file. -->  
  <trace autoflush="false">  
    <listeners>  
      ...
      <add name="storageListener" />  
    </listeners>  
  </trace>  
  <sources>  
    <source name="Microsoft.Azure.Storage">  
      <listeners>  
        <add name="storageListener"/>  
      </listeners>  
    </source>  
  </sources>  
  <switches>  
    <add name="Microsoft.Azure.Storage" value="Verbose" />  
  </switches>  
  <sharedListeners>  
    <add name="storageListener"  
      type="System.Diagnostics.TextWriterTraceListener"  
      initializeData="C:\logs\WebRole.log"
      traceOutputOptions="DateTime" />  
  </sharedListeners>  
</system.diagnostics>

注意

.NET Framework 使用版本 4.6.1-4.7.1 (（含) 版本 4.6.1-4.7.1）的用户在使用 Azure 存储库的 .NET Standard 2.0 项目时可能会遇到日志记录问题，Visual Studio 的 NuGet 包管理器可能会自动选择这些项目。这些库还作为 4.5.2 项目.NET Framework发布，它们不会遇到这些问题。有关详细信息，请阅读 .NET Standard 版本支持。

此示例将客户端库配置为将日志消息写入物理文件 C:\logs\WebRole.log。还可以使用其他跟踪侦听器（例如 EventLogTraceListener ）写入 Windows 事件日志，或使用 EventProviderTraceListener 将跟踪数据写入 ETW 子系统。

重要

日志文件的完整文件夹路径必须存在于本地文件系统上。在此示例中，这意味着必须先创建文件夹， C:\logs 然后再将日志写入该文件夹中的文件。

此外，可以将 autoflush 设置为 true，以便立即将日志条目写入文件，而不是缓冲它们。此设置在跟踪消息量较少的开发/测试环境中可能很有用，但在生产环境中，可能需要将 autoflush 设置为 false。使用配置设置启用客户端跟踪 (并为客户端中所有存储操作) 的所有消息指定级别（如详细）。

ID	日志级别	事件
0	关	不记录任何内容。
1	错误	如果无法在内部处理异常并向用户引发异常，则会将其记录为错误。
2	警告	如果异常在内部捕获并处理，则会将其记录为警告。此日志级别的主要用例是重试方案，其中异常不会引发回用户重试。此行为也可能发生在 CreateIfNotExists 等操作中，其中 404 错误以无提示方式处理。
3	信息	记录以下信息： •在用户调用方法启动操作后，将记录请求详细信息，例如 URI 和客户端请求 ID。 •记录重要里程碑（如发送请求开始/结束、上传数据开始/结束、接收响应开始/结束、下载数据开始/结束）以标记时间戳。 •在收到标头后，将记录响应详细信息，例如请求 ID 和 HTTP 状态代码。 •如果操作失败，并且存储客户端决定重试，则会记录该决策的原因以及有关下次重试时间的信息。 •当存储客户端决定中止挂起的请求时，将记录所有客户端超时。
4	详细	记录以下信息： •每个请求的字符串到签名。 •特定于操作的任何额外详细信息 (每个操作定义和使用) 。

默认情况下，客户端库会在配置文件中指定的详细级别记录所有存储操作的详细信息。还可以将日志记录限制为客户端应用程序的特定区域，以减少记录的数据量并帮助你找到所需的信息。若要限制写入日志的数据量，必须将一些代码添加到客户端应用程序。通常，在配置文件中启用客户端跟踪后，使用 OperationContext 类在代码中全局关闭它。例如，在应用程序执行任何存储操作之前，可以在 Application_Start 方法的 ASP.NET MVC 应用程序中执行此操作：

protected void Application_Start()  
{  
    ...  
  
    // Disable Default Logging for Windows Azure Storage  
    OperationContext.DefaultLogLevel = LogLevel.Off;  
  
    // Verify that all of the tables, queues, and blob containers used in this application  
    // exist, and create any that don't already exist.  
    CreateTablesQueuesBlobContainers();  
}

然后，可以通过创建定义日志记录级别的自定义 OperationContext 对象，为感兴趣的特定操作启用跟踪。然后，将 OperationContext 对象作为参数传递给用于调用存储操作的 Execute 方法，如以下示例所示：

[HttpPost]  
[ValidateAntiForgeryToken]  
public ActionResult Create(Subscriber subscriber)  
{  
    if (ModelState.IsValid)  
    {  
       ...  
        var insertOperation = TableOperation.Insert(subscriber);  
        OperationContext verboseLoggingContext = new OperationContext() { LogLevel = LogLevel.Verbose };  
        mailingListTable.Execute(insertOperation, null, verboseLoggingContext);  
        return RedirectToAction("Index");  
    }  
  
    ...  
    return View(subscriber);  
}

客户端日志架构和示例

以下示例是从客户端库为包含 c3aa328b 的客户端请求 ID 的操作生成的客户端日志中提取。客户端请求 ID 是一个相关标识符，它允许在客户端上记录的消息与网络跟踪和存储日志相关联。有关关联的详细信息，请参阅监视、诊断和排查 Azure 存储问题。该摘要包括可从日志文件中观察到的某些关键信息的注释（缩进和斜体形式）。

为了说明此功能，请使用以下日志文件的第一行，字段为：

日志字段	值
Source	Microsoft.Azure.Storage
Verbosity	信息
详细编号	3
客户端请求 ID	c3aa328b...
操作文本	正在按位置模式 PrimaryOnly 使用主位置启动操作。

Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting operation with location Primary per location mode PrimaryOnly.
前面的跟踪消息显示位置模式设置为仅主要位置，这意味着失败的请求不会发送到辅助位置。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Starting synchronous request to https://storageaccountname.table.core.windows.net/mailinglist.
前面的跟踪消息显示请求是同步的。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Setting payload format for the request to 'Json'.
前面的跟踪消息显示响应应返回格式为 JSON。
Microsoft.Azure.Storage Verbose: 4 : c3aa328b...: StringToSign = GET...Fri, 23 May 2014 06:19:48 GMT./storageaccountname/mailinglist.
前面的跟踪消息包含 StringToSign 信息，这对于调试身份验证失败很有用。详细消息还包含完整的请求详细信息，包括操作类型和请求参数。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Waiting for response.
前面的跟踪消息显示请求已发送，客户端正在等待响应。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response received. Status code = 200, Request ID = 417db530-853d-48a7-a23c-0c8d5f728178, Content-MD5 = , ETag =
前面的跟踪消息显示已收到响应及其 http 状态代码。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Response headers were processed successfully, proceeding with the rest of the operation.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Processing response body.
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Retrieved '8' results with continuation token ''.
前面的跟踪消息显示检索了 8 个结果，并且未提供任何延续标记，这意味着此查询没有更多结果。
Microsoft.Azure.Storage Information: 3 : c3aa328b...: Operation completed successfully.
前面的跟踪消息显示操作已成功完成。

以下两个详细 (级别 4) 日志条目显示了HEAD和 DELETE 请求，并说明了“操作文本”字段中的详细信息：
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = HEAD............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:11 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
Microsoft.Azure.Storage Verbose: 4 : 07b26a5d...: StringToSign = DELETE............x-ms-client-request-id:07b26a5d....x-ms-date:Tue, 03 Jun 2014 10:33:12 GMT.x-ms-version:2014-02-14./storageaccountname/azuremmblobcontainer.restype:container.
前面的跟踪消息显示详细跟踪消息中的 OperationText 字段，包括与特定请求相关的详细信息。这些详细信息包括 HTTP 操作类型 (例如，HEAD、DELETE、POST) 、客户端请求 ID、时间戳、SDK 版本和其他特定于操作的数据。

使用适用于 .NET 的客户端库进行客户端日志记录

如何启用客户端库日志记录

客户端日志架构和示例

其他资源