在 Application Insights 中浏览 .NET/.NET Core 和 Python 跟踪日志

项目
07/09/2024

将 ASP.NET/ASP.NET Core 应用程序的诊断跟踪日志从 ILogger、NLog、log4Net 或 System.Diagnostics.Trace 发送到 Azure Application Insights。对于 Python 应用程序，使用适用于 Azure Monitor 的 OpenCensus Python 中的 AzureLogHandler 发送诊断跟踪日志。然后，可以浏览并搜索它们。这些日志与你的应用程序中的其他日志文件合并。可以使用它们来识别与每个用户请求关联的跟踪，并将跟踪与其他事件和异常报告关联。

注意

是否需要日志捕获模块？它是适用于第三方记录器的适配器。但是如果未使用 NLog、log4Net 或 System.Diagnostics.Trace，请考虑直接调用 Application Insights TrackTrace()。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。检测密钥引入功能将会继续工作，但我们将不再为该功能提供更新或支持。转换为连接字符串，以利用新功能。

在应用上安装记录

在项目中安装所选的日志框架，这将导致在 app.config 或 web.config 中生成一个条目。

 <configuration>
  <system.diagnostics>
    <trace>
      <listeners>
        <add name="myAppInsightsListener" type="Microsoft.ApplicationInsights.TraceListener.ApplicationInsightsTraceListener, Microsoft.ApplicationInsights.TraceListener" />
      </listeners>
    </trace>
  </system.diagnostics>
</configuration>

配置 Application Insights 以收集日志

将 Application Insights 添加到项目，前提是尚未执行此操作且有一个选项可以包括日志收集器。

或者右键单击解决方案资源管理器中的项目以配置 Application Insights。选择“配置跟踪集合”选项。

注意

没有 Application Insights 菜单或日志收集器选项？尝试故障排除。

手动安装

如果项目类型不受 Application Insights 安装程序支持，请使用此方法。例如，如果项目类型是 Windows 桌面项目。

如果计划使用 log4net 或 NLog，请在项目中安装它。
在“解决方案资源管理器”中，右键单击项目并选择“管理 NuGet 包”.
搜索“Application Insights”。
选择以下包之一：
- ILogger：Microsoft.Extensions.Logging.ApplicationInsights
- NLog：Microsoft.ApplicationInsights.NLogTarget
- log4net：Microsoft.ApplicationInsights.Log4NetAppender
- System.Diagnostics：Microsoft.ApplicationInsights.TraceListener
- Microsoft.ApplicationInsights.DiagnosticSourceListener
- Microsoft.ApplicationInsights.EtwCollector
- Microsoft.ApplicationInsights.EventSourceListener

NuGet 包安装必要的程序集，并在适用情况下修改 web.config 或 app.config。

ILogger

有关将 Azure Application Insights ILogger 实现与控制台应用程序及 ASP.NET Core 配合使用的示例，请参阅适用于 .NET Core ILogger 日志的 ApplicationInsightsLoggerProvider。

插入诊断日志调用

如果使用 System.Diagnostics.Trace，则典型的调用将是：

System.Diagnostics.Trace.TraceWarning("Slow response - database01");

如果首选 log4net 或 NLog，请使用：

    logger.Warn("Slow response - database01");

使用 EventSource 事件

可配置要作为跟踪发送到 Application Insights 的 System.Diagnostics.Tracing.EventSource 事件。首先，安装 Microsoft.ApplicationInsights.EventSourceListener NuGet 包。然后编辑 ApplicationInsights.config 文件的 TelemetryModules 部分。

    <Add Type="Microsoft.ApplicationInsights.EventSourceListener.EventSourceTelemetryModule, Microsoft.ApplicationInsights.EventSourceListener">
      <Sources>
        <Add Name="MyCompany" Level="Verbose" />
      </Sources>
    </Add>

可对每个资源设置以下参数：

“名称”指定要收集的 EventSource 的名称。
“级别”指定要收集的日志记录级别：严重、错误、信息性、LogAlways、详细或警告。
“关键字”（可选）指定要使用的关键字组合的整数值。

使用 DiagnosticSource 事件

可配置要作为跟踪发送到 Application Insights 的 System.Diagnostics.DiagnosticSource 事件。首先，安装 Microsoft.ApplicationInsights.DiagnosticSourceListener NuGet 包。然后编辑 ApplicationInsights.config 文件的“TelemetryModules”部分。

    <Add Type="Microsoft.ApplicationInsights.DiagnosticSourceListener.DiagnosticSourceTelemetryModule, Microsoft.ApplicationInsights.DiagnosticSourceListener">
      <Sources>
        <Add Name="MyDiagnosticSourceName" />
      </Sources>
    </Add>

对于要跟踪的每个诊断源，请在诊断源名称中添加包含 Name 属性集的项。

使用 ETW 事件

可配置要作为跟踪发送到 Application Insights 的 Windows 事件跟踪 (ETW) 事件。首先，安装 Microsoft.ApplicationInsights.EtwCollector NuGet 包。然后编辑 ApplicationInsights.config 文件的“TelemetryModules”部分。

注意

托管 SDK 的进程以“性能日志用户”或管理员成员身份运行时才可收集 ETW 事件。

    <Add Type="Microsoft.ApplicationInsights.EtwCollector.EtwCollectorTelemetryModule, Microsoft.ApplicationInsights.EtwCollector">
      <Sources>
        <Add ProviderName="MyCompanyEventSourceName" Level="Verbose" />
      </Sources>
    </Add>

可对每个资源设置以下参数：

“ProviderName”是要收集的 ETW 提供程序的名称。
“ProviderGuid”指定要收集的 ETW 提供程序的 GUID。可以使用它，而不是使用 ProviderName。
“级别”设置要收集的日志记录级别。它可以是“严重”、“错误”、“信息性”、“LogAlways”、“详细”或“警告” 。
“关键字”（可选）设置要使用的关键字组合的整数值。

直接使用跟踪 API

可以直接调用 Application Insights 跟踪 API。日志记录适配器使用此 API。

例如：

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow response - database01");

TrackTrace 的一个优点是可将相对较长的数据放置在消息中。例如，可在此处对 POST 数据进行编码。

还可向消息添加严重性级别。并像其他遥测一样，可以添加属性值以帮助筛选或搜索不同跟踪集。例如：

TelemetryConfiguration configuration = TelemetryConfiguration.CreateDefault();
var telemetryClient = new TelemetryClient(configuration);
telemetryClient.TrackTrace("Slow database response",
                            SeverityLevel.Warning,
                            new Dictionary<string, string> { { "database", "db.ID" } });

现在可在“事务搜索”中轻松筛选出与特定数据库相关的所有特定严重性级别的消息。

适用于 OpenCensus Python 的 AzureLogHandler

Azure Monitor 日志处理程序允许将 Python 日志导出到 Azure Monitor。

使用适用于 Azure Monitor 的 OpenCensus Python SDK 检测应用程序。

此示例演示如何将警告级别日志发送到 Azure Monitor。

import logging

from opencensus.ext.azure.log_exporter import AzureLogHandler

logger = logging.getLogger(__name__)
logger.addHandler(AzureLogHandler(connection_string='InstrumentationKey=<your-instrumentation_key-here>'))
logger.warning('Hello, World!')

浏览日志

在调试模式下运行应用，或者实时部署它。

在 Application Insights 门户中应用的概述窗格中，选择“事务搜索”。

例如，可以：

对日志跟踪或具有特定属性的项目进行筛选。
检查详细信息中的特定项。
查找与相同用户请求（具有相同的操作 ID）相关的其他系统日志数据。
将页面的配置另存为收藏夹。

注意

如果应用程序发送大量数据，并且使用的是用于 ASP.NET 的 Application Insights SDK 2.0.0-beta3 或更高版本，则自适应采样功能可以正常运行，只发送一部分遥测数据。了解有关采样的详细信息。

疑难解答

找到常见问题的答案。

导致遥测延迟、网络重载或传输效率低下的原因是什么？

System.Diagnostics.Tracing 具有自动刷新功能。此功能会导致 SDK 刷新每个遥测项，此操作是不必要的，并且可能导致日志记录适配器问题，如遥测延迟、网络重载、传输效率低下等。

对于 Java，我该怎么做？

在 Java 无代码检测（推荐）中，日志是现成收集的。使用 Java 3.0 代理。

Application Insights Java 代理从 Log4j、Logback 和 java.util.logging 收集日志。

请确保 Developer Analytics Tools 安装在开发计算机上。在 Visual Studio 中，转到“工具”>“扩展和更新”，查找“Developer Analytics Tools”。如果它不在“已安装”选项卡中，请打开“联机”选项卡并安装它。
此项目类型可能是 Developer Analytics Tools 不支持的项目类型。使用手动安装。

为什么配置工具中没有日志适配器选项？

首先安装记录框架。
如果使用的是 System.Diagnostics.Trace，请确保已在 web.config 中对其进行配置。
确保已安装最新版本的 Application Insights。在 Visual Studio 中，转到“工具”>“扩展和更新”，并打开“更新”选项卡。如果其中显示了“Developer Analytics Tools”，请选择它进行更新。

为什么我会遇到“检测密钥不能为空”错误消息？

你可能在未安装 Application Insights 的情况下安装了日志记录适配器 NuGet 包。在解决方案资源管理器中，右键单击“ApplicationInsights.config”，然后选择“更新 Application Insights”。系统将提示你登录到 Azure 并创建 Application Insights 资源或重复使用现有资源。这会解决此问题。

为什么我可以在诊断搜索中看到跟踪，但看不到其他事件？

所有事件和请求都通过管道可能需要一些时间。

会保留多少数据？

多个因素会影响保留的数据量。有关详细信息，请参阅客户事件指标页的限制部分。

为什么我看不到所需的一些日志条目？

也许应用程序发送了大量数据，并且你使用的是用于 ASP.NET 的 Application Insights SDK 2.0.0-beta3 或更高版本。在这种情况下，自适应采样功能可以正常运行，只发送一部分遥测数据。了解有关采样的详细信息。

通过