.NET自动仪表化问题的故障排除

通用步骤

如果您在使用OpenTelemetry .NET自动仪表化时遇到任何问题，可以采取以下步骤来帮助您了解问题。

启用详细日志记录

详细的调试日志可以帮助您排查仪表化问题，并且可以附加到该项目中的问题中以便进行调查。

要获取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分析器无法附加，因此不会生成日志。

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

无法安装软件包’OpenTelemetry.AutoInstrumentation.Runtime.Native'

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

无法安装软件包'OpenTelemetry.AutoInstrumentation.Runtime.Native 1.0.0-rc.1'。您正在尝试将此软件包安装到目标为'.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自动仪表化使用以下依赖项：

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

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

如果应用程序已经为自动仪表化使用的程序集提供了绑定重定向，则此自动重定向可能会失败，请参阅#2833。检查是否有任何现有的绑定重定向阻止重定向到在netfx_assembly_redirection.h中列出的版本。

为了使上述的自动重定向能够正常工作，有两个特定的场景需要将用于仪表化.NET Framework应用程序的位于安装目录的netfx文件夹中的程序集也安装到全局程序集缓存（GAC）中：

猴子补丁仪表化，用于加载为域中立的程序集。
对于具有强名称的应用程序，如果该应用程序还提供了与位于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

其他问题

如果您遇到此页面中未列出的问题，请参阅通用步骤以收集额外的诊断信息。这可能有助于简化故障排除的过程。

最后修改 December 10, 2023: translate (a4350d6e)