.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 パッケージをプロジェクトに追加する際に、以下のようなエラーメッセージが表示されます。

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 に移行してください。

パフォーマンスの問題

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 パッケージをアプリケーションに追加することです。 アプリケーションへの追加方法については、Using the OpenTelemetry.AutoInstrumentation NuGet packages を参照してください。

フレームワーク依存のスタンドアロン .NET デプロイメントで、自動アセンブリリダイレクトが競合を解決できない場合やリダイレクトを無効にする必要がある場合は、AdditionalDeps と共有ストアの回避策を使用してください。

または、競合するパッケージのみをプロジェクトに追加してください。 以下の依存関係が OpenTelemetry .NET 自動計装で使用されています。

バージョンは以下の場所で確認できます。

アセンブリリダイレクトはスタンドアロンデプロイメントではデフォルトで有効、NuGet パッケージデプロイメントでは無効です。 この動作は OTEL_DOTNET_AUTO_REDIRECT_ENABLED 設定で制御できます。 NuGet パッケージでアセンブリの読み込みエラーが発生する場合は、この設定が明示的に有効になっていないことを確認してください。

アプリケーションが自動計装で使用されるアセンブリのバインディングリダイレクトをすでに含んでいる場合、この自動リダイレクトが失敗する可能性があります。 #2833 を参照してください。 既存のバインディングリダイレクトが .NET アプリケーション用の assembly_redirection_net.h および .NET Framework アプリケーション用の assembly_redirection_netfx.h に記載されたバージョンへのリダイレクトを妨げていないか確認してください。 .NET 10 以降の UnsafeAccessorTypeAttribute メタデータリダイレクトを含む解決方法の詳細については、Assembly Conflict Resolution を参照してください。

上記の自動リダイレクトが機能するためには、.NET Framework アプリケーションの計装に使用されるアセンブリ（インストールディレクトリの netfx フォルダー配下のもの）をグローバルアセンブリキャッシュ（GAC）にもインストールする必要がある、2つの特定のシナリオがあります。

  1. モンキーパッチ計装：ドメインニュートラルとして読み込まれたアセンブリの場合。
  2. アセンブリリダイレクト：厳密な名前付きアプリケーションで、アプリケーションが netfx フォルダーにも含まれる一部のアセンブリの異なるバージョンを同梱している場合。

上記のシナリオのいずれかで問題が発生している場合は、PowerShell インストールモジュールから Install-OpenTelemetryCore コマンドを再度実行して、必要な GAC インストールが更新されていることを確認してください。

自動計装による GAC の使用方法の詳細については、pjanotti’s comment を参照してください。

詳細については、#2269 と #2296 を参照してください。

AdditionalDeps と共有ストアの回避策

スタンドアロンディストリビューションには、ディストリビューションに含まれる依存関係から依存関係マニフェストと共有ストアディレクトリを生成するスクリプトが含まれています。 この回避策は、フレームワーク依存のスタンドアロン .NET アプリケーションで、自動アセンブリリダイレクトが競合を解決できない場合やリダイレクトを無効にする必要がある場合に使用してください。

アプリケーションを起動する前に、専用の書き込み可能な出力ディレクトリを選択し、使用しているオペレーティングシステム用のスクリプトを実行してください。

Linux と macOS の場合：

"$OTEL_DOTNET_AUTO_HOME/generate-additional-deps.sh" \
  --output /var/lib/otel-dotnet-auto/additional-deps

Windows の場合：

& "$env:OTEL_DOTNET_AUTO_HOME\generate-additional-deps.ps1" `
    -OutputPath "C:\ProgramData\OpenTelemetry\additional-deps"

スクリプトが出力したパスを使用して、アプリケーションに以下の環境変数を設定してください。

DOTNET_ADDITIONAL_DEPS=<output>/AdditionalDeps
DOTNET_SHARED_STORE=<output>/store

アプリケーションでアセンブリリダイレクトも無効にする必要がある場合は、OTEL_DOTNET_AUTO_REDIRECT_ENABLED=false を設定してください。

この回避策には以下の制限事項があります。

  • フレームワーク依存のスタンドアロン .NET アプリケーションにのみ適用されます。 .NET Framework および自己完結型アプリケーションでは使用できません。 NuGet パッケージデプロイメントはアプリケーションの NuGet グラフを通じて依存関係を解決します。
  • 明示的なアセンブリ読み込みやカスタム AssemblyLoadContext の実装は、生成された依存関係グラフをバイパスする可能性があります。
  • 生成されたファイルはディストリビューションのアーキテクチャ、ターゲットフレームワーク、依存関係のバージョンに依存します。 計装のアップグレードごとにクリーンな出力ディレクトリに再生成してください。 異なるバージョンのファイルを混在させないでください。
  • 依存関係グラフはアプリケーション全体に適用されます。 有効化後、特に同じ依存関係の異なるバージョンを参照している場合は、アプリケーションを検証してください。

詳細については、上流の AdditionalDeps and shared-store workaround を参照してください。

AdditionalDeps 内のアセンブリが見つからない

症状

以下のようなエラーメッセージが表示されます。

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

これは以下のイシューに関連している可能性があります。

その他の問題

このページに記載されていない問題が発生した場合は、一般的な手順を参照して追加の診断情報を収集してください。 これによりトラブルシューティングが容易になる可能性があります。


最終更新 October 31, 2026: [ja] update translation of content/en/docs/zero-code/dotnet/troubleshooting.md (#12469) (0844d7d5)