Усунення несправностей автоматичного інструментування .NET

Загальні кроки

Якщо ви зіткнулися з будь-якою проблемою з OpenTelemetry .NET Automatic Instrumentation, є кроки, які можуть допомогти вам зрозуміти проблему.

Увімкніть детальне ведення журналу

Детальні журнали налагодження можуть допомогти вам усунути проблеми з інструментуванням і можуть бути додані до повідомлення у цьому проєкті для полегшення розслідування.

Щоб отримати детальні журнали від OpenTelemetry .NET Automatic Instrumentation, встановіть змінну середовища OTEL_LOG_LEVEL на debug перед запуском інструментованого процесу.

Стандартно бібліотека записує файли журналів у попередньо визначені місця. Якщо потрібно, змініть стандартне місце, оновіть змінну середовища OTEL_DOTNET_AUTO_LOG_DIRECTORY.

Після отримання журналів видаліть змінну середовища OTEL_LOG_LEVEL або встановіть її на менш докладний рівень, щоб уникнути непотрібних накладних витрат.

Увімкніть трасування хосту

Трасування хосту може бути використане для збору інформації, необхідної для розслідування проблем, повʼязаних з різними питаннями, такими як не знайдені збірки. Встановіть наступні змінні середовища:

COREHOST_TRACE=1
COREHOST_TRACEFILE=corehost_verbose_tracing.log

Потім перезапустіть застосунок, щоб зібрати логи.

Поширені проблеми

Не створюється телеметрія

Телеметрія не створюється. У місці для внутрішніх журналів OpenTelemetry .NET Automatic Instrumentation немає логів.

Можливо, що .NET Profiler не може приєднатися, і тому журнали не будуть створені.

Найпоширенішою причиною є те, що інструментованому застосунку не вистачає дозволів для завантаження збірок OpenTelemetry .NET Automatic Instrumentation.

Не вдалося встановити пакунок ‘OpenTelemetry.AutoInstrumentation.Runtime.Native’

При додаванні пакунків NuGet до вашого проєкту ви отримуєте повідомлення про помилку, подібне до:

Could not install package 'OpenTelemetry.AutoInstrumentation.Runtime.Native 1.6.0'. You are trying to install this package into a project that targets '.NETFramework,Version=v4.7.2', but the package does not contain any assembly references or content files that are compatible with that framework. For more information, contact the package author.

Пакунки NuGet не підтримують проєкти старого стилю csproj. Або розгорніть автоматичне інструментування на машині замість використання пакунків NuGet, або переведіть свій проєкт на стиль SDK csproj.

Проблеми з продуктивністю

Якщо виникає високе завантаження процесора, переконайтеся, що ви не увімкнули автоматичне інструментування глобально, встановивши змінні середовища на рівні системи або користувача.

Якщо використання системного або користувацького рівня є навмисним, використовуйте змінні середовища OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES, щоб виключити застосунки з автоматичного інструментування.

Інструмент командного рядка dotnet аварійно завершує роботу

Ви отримуєте повідомлення про помилку, подібне до наведеного нижче, при запуску застосунку, наприклад з 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.

Тому, якщо ви використовуєте одну з цих версій, ми радимо виконати 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

Пакунки NuGet OpenTelemetry .NET та їх залежності розгортаються з OpenTelemetry .NET Automatic Instrumentation.

Щоб вирішити конфлікти версій залежностей, оновіть посилання на проєкт інструментованого застосунку, щоб використовувати ті ж версії, що й OpenTelemetry .NET Automatic Instrumentation.

Простий спосіб забезпечити відсутність таких конфліктів — додати пакунок OpenTelemetry.AutoInstrumentation до вашого застосунку. Для інструкцій про те, як додати його до вашого застосунку, дивіться Використання пакунків NuGet OpenTelemetry.AutoInstrumentation.

Альтернативно додайте лише пакунки, що конфліктують, до вашого проєкту. Наступні залежності використовуються OpenTelemetry .NET Automatic Instrumentation:

Знайдіть їх версії в наступних місцях:

Стандартно посилання на збірки для застосунків .NET Framework перенаправляються під час виконання на версії, що використовуються автоматичним інструментуванням. Ця поведінка може бути керована через налаштування OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED.

Якщо застосунок вже містить перенаправлення привʼязок для збірок, що використовуються автоматичним інструментуванням, це автоматичне перенаправлення може не вдатися, дивіться #2833. Перевірте, чи не заважає будь-яке наявне перенаправлення привʼязок перенаправленню на версії, перелічені в netfx_assembly_redirection.h.

Для того, щоб автоматичне перенаправлення вище працювало, є два конкретні сценарії, які вимагають, щоб збірки, що використовуються для інструментування додатків .NET Framework, ті, що знаходяться в теці netfx теки встановлення, також були встановлені в Глобальний кеш збірок (GAC):

  1. Monkey-патчинг збірок, завантажених як нейтральні до домену.
  2. Перенаправлення збірок для застосунків зі строгими іменами, якщо застосунок також містить різні версії деяких збірок, також поставлених у теці netfx.

Якщо у вас виникають проблеми в одному з наведених вище сценаріїв, знову запустіть команду Install-OpenTelemetryCore з модуля встановлення PowerShell, щоб переконатися, що необхідні установки GAC оновлені.

Для отримання додаткової інформації про використання GAC автоматичним інструментуванням дивіться коментар pjanotti.

Дивіться #2269 та #2296 для отримання додаткової інформації.

Збірка в AdditionalDeps не знайдена

Симптоми

Ви отримуєте повідомлення про помилку, подібне до наступного:

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

Це може бути повʼязано з наступними проблемами:

Інші проблеми

Якщо ви зіткнулися з проблемою, не зазначеною на цій сторінці, дивіться Загальні кроки для збору додаткової діагностичної інформації. Це може допомогти полегшити усунення несправностей.


Востаннє змінено June 5, 2025: [uk] spellchecking (8ca5a3a5)