.NET 自动检测问题故障排除

常规步骤

如果您在使用 OpenTelemetry .NET 自动检测时遇到任何问题，以下步骤可以帮助您了解问题所在。

启用详细日志

详细的调试日志可以帮助您排查检测问题，并可以附加到项目的 issues 中以便进行调查。

要获取 OpenTelemetry .NET 自动检测的详细日志，请在被检测进程启动前设置 OTEL_LOG_LEVEL 环境变量为 debug。

默认情况下，库会将日志文件写入预定义的位置。如有需要，可以通过更新 OTEL_DOTNET_AUTO_LOG_DIRECTORY 环境变量来更改默认位置。

获取日志后，请移除 OTEL_LOG_LEVEL 环境变量，或将其设置为较低的详细级别以避免不必要的开销。

启用主机跟踪

主机跟踪可用于收集调查各种问题所需的信息，比如找不到程序集等问题。设置以下环境变量：

COREHOST_TRACE=1
COREHOST_TRACEFILE=corehost_verbose_tracing.log

然后重启应用程序以收集日志。

常见问题

未产生遥测数据

没有生成遥测数据。在 OpenTelemetry .NET 自动检测内部日志位置中没有日志。

可能是 .NET Profiler 无法附加，因此不会输出任何日志。

最常见的原因是被检测的应用程序没有权限加载 OpenTelemetry .NET 自动检测程序集。

无法安装 'OpenTelemetry.AutoInstrumentation.Runtime.Native' 包

当向项目添加 NuGet 包时，您收到类似以下的错误消息：

无法安装包 'OpenTelemetry.AutoInstrumentation.Runtime.Native 1.6.0'。您正在尝试将此包安装到目标为 '.NETFramework,Version=v4.7.2' 的项目中，但该包不包含与该框架兼容的任何程序集引用或内容文件。有关更多信息，请联系包作者。

NuGet 包不支持旧式 csproj 项目。您可以选择将自动检测部署到机器上而不使用 NuGet 包，或者将项目迁移到 SDK 风格的 csproj。

性能问题

如果出现高 CPU 使用率，请确保您没有通过在系统或用户范围设置环境变量来全局启用自动检测。

如果使用系统或用户范围是有意为之，请使用 OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES 环境变量来排除不需要自动检测的应用程序。

dotnet CLI 工具崩溃

当运行应用程序时（例如使用 dotnet run），您收到类似以下的错误消息：

PS C:\Users\Administrator\Desktop\OTelConsole-NET6.0> dotnet run My.Simple.Console
Unhandled exception. System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.TypeInitializationException: The type initializer for 'OpenTelemetry.AutoInstrumentation.Loader.Startup' threw an exception.
---> System.Reflection.TargetInvocationException: Exception has been thrown by the target of an invocation.
---> System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.Configuration.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

在 v0.6.0-beta.1 及更低版本中，在检测 dotnet CLI 工具时存在问题。

因此，如果您使用的是这些版本，我们建议在检测终端会话之前执行 dotnet build，或在单独的终端会话中调用它。

更多信息请参见 #1744。

程序集版本冲突

类似以下的错误消息：

Unhandled exception. System.IO.FileNotFoundException: Could not load file or assembly 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'. The system cannot find the file specified.

File name: 'Microsoft.Extensions.DependencyInjection.Abstractions, Version=7.0.0.0, Culture=neutral, PublicKeyToken=adb9793829ddae60'
   at Microsoft.AspNetCore.Builder.WebApplicationBuilder..ctor(WebApplicationOptions options, Action`1 configureDefaults)
   at Microsoft.AspNetCore.Builder.WebApplication.CreateBuilder(String[] args)
   at Program.<Main>$(String[] args) in /Blog.Core/Blog.Core.Api/Program.cs:line 26

OpenTelemetry .NET NuGet 包及其依赖项随 OpenTelemetry .NET 自动检测一起部署。

要处理依赖项版本冲突，请更新被检测应用程序的项目引用，使用与 OpenTelemetry .NET 自动检测相同的版本。

确保不会发生此类冲突的简单方法是将 OpenTelemetry.AutoInstrumentation 包添加到您的应用程序中。有关如何将其添加到应用程序的说明，请参见使用 OpenTelemetry.AutoInstrumentation NuGet 包。

或者只将冲突的包添加到您的项目中。以下是 OpenTelemetry .NET 自动检测使用的依赖项：

• OpenTelemetry.AutoInstrumentation
• OpenTelemetry.AutoInstrumentation.AdditionalDeps

在以下位置查找它们的版本：

• Directory.Packages.props
• src/Directory.Packages.props
• src/OpenTelemetry.AutoInstrumentation.AdditionalDeps/Directory.Packages.props

默认情况下，.NET Framework 应用程序的程序集引用在运行时会重定向到自动检测使用的版本。此行为可以通过 OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED 设置来控制。

如果应用程序已经为自动检测使用的程序集配置了绑定重定向，这种自动重定向可能会失败，请参见 #2833。检查是否有任何现有的绑定重定向阻止重定向到 netfx_assembly_redirection.h 中列出的版本。

对于上述自动重定向，有两种特定场景需要将用于检测 .NET Framework 应用程序的程序集（安装目录的 netfx 文件夹下的程序集）也安装到全局程序集缓存（GAC）中：

1. 对加载为域中立的程序集进行猴子补丁检测。
2. 如果应用程序还附带了与 netfx 文件夹中相同的程序集的不同版本，则需要对具有强名称的应用程序进行程序集重定向。

如果您在上述场景中遇到问题，请再次从 PowerShell 安装模块运行 Install-OpenTelemetryCore 命令，以确保所需的 GAC 安装已更新。

有关自动检测使用 GAC 的更多信息，请参见此处。

更多信息请参见 #2269 和 #2296。

未找到 AdditionalDeps 中的程序集

症状

您收到类似以下的错误消息：

An assembly specified in the application dependencies manifest (OpenTelemetry.AutoInstrumentation.AdditionalDeps.deps.json) was not found

这可能与以下问题有关：

• #1744
• #2181