構成と設定

構成方法

以下の方法で構成設定を適用または編集できます。 環境変数は App.config や Web.config ファイルよりも優先されます。

1. 環境変数

   環境変数は設定を構成する主な方法です。

2. App.config または Web.config ファイル

   .NET Framework 上で動作するアプリケーションの場合、Web 構成ファイル（web.config）やアプリケーション構成ファイル（app.config）を使用して OTEL_* 設定を構成できます。

   ⚠️ App.config や Web.config を使用して設定できるのは、OTEL_ で始まる設定のみです。 ただし、以下の設定はサポートされていません。

   • OTEL_DOTNET_AUTO_HOME
   • OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES
   • OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_[TRACES|METRICS|LOGS]_{INSTRUMENTATION_ID}_INSTRUMENTATION_ENABLED
   • OTEL_DOTNET_AUTO_LOG_DIRECTORY
   • OTEL_LOG_LEVEL
   • OTEL_DOTNET_AUTO_NETFX_REDIRECT_ENABLED（非推奨）
   • OTEL_DOTNET_AUTO_REDIRECT_ENABLED
   • OTEL_DOTNET_AUTO_SQLCLIENT_NETFX_ILREWRITE_ENABLED

   OTEL_SERVICE_NAME の設定例:

   <configuration>
   <appSettings>
       <add key="OTEL_SERVICE_NAME" value="my-service-name" />
   </appSettings>
   </configuration>
   

   注記

   .NET Framework では、Web.config や App.config の OTEL_* 値は起動時にプロセスレベルの環境変数に昇格され、OTel SDK はプロセスごとに一度だけ初期化されます。 IIS では複数のアプリケーションが単一のワーカープロセス（アプリケーションプール）を共有できるため、最初に起動したアプリケーションがそのプール内のすべてのアプリケーションの構成を決定します。

3. サービス名の自動検出

   サービス名が明示的に構成されていない場合、自動的に生成されます。 これはいくつかの状況で役立ちます。

   • アプリケーションが .NET Framework の IIS 上でホストされている場合、SiteName\VirtualPath（例: MySite\MyApp）になります。
   • それ以外の場合は、アプリケーションの Entry Assembly の名前が使用されます。

デフォルトでは、構成に環境変数を使用することを推奨します。 ただし、特定の設定がサポートしている場合は次のようにします。

• ASP.NET アプリケーション（.NET Framework）の構成には Web.config を使用します。
• Windows サービス（.NET Framework）の構成には App.config を使用します。

グローバル設定

[1] OTEL_DOTNET_AUTO_FAIL_FAST_ENABLED が true に設定されている場合、OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES によって計装から除外されたプロセスは、サイレントに続行するかわりにフェイルします。

[2] dotnet MyApp.dll で起動されたアプリケーションのプロセス名は dotnet または dotnet.exe であることに注意してください。

リソース

リソースは、テレメトリーを生成しているエンティティの不変の表現です。 詳細については、リソースのセマンティック規約を参照してください。

リソース属性

リソースディテクター

以下のリソースディテクターがデフォルトで組み込まれ、有効になっています。

プロパゲーター

プロパゲーターはアプリケーション間でコンテキストを共有できるようにします。 詳細については、OpenTelemetry 仕様を参照してください。

サンプラー

サンプラーを使用すると、収集およびエクスポートするトレースを選択することで、OpenTelemetry の計装によって発生する潜在的なノイズやオーバーヘッドを制御できます。 詳細については、OpenTelemetry 仕様を参照してください。

[1]: サポートされる値:

• always_on
• always_off
• traceidratio
• parentbased_always_on
• parentbased_always_off
• parentbased_traceidratio

[2]: traceidratio および parentbased_traceidratio サンプラーの場合: サンプリング確率。[0..1] の範囲の数値です（例: “0.25”）。 デフォルトは 1.0 です。

エクスポーター

エクスポーターはテレメトリーを出力します。

[1]: zipkin は非推奨であり、今後のリリースで削除されます。

トレースエクスポーター

メトリクスエクスポーター

ログエクスポーター

OTLP

ステータス: Stable

OTLP エクスポーターを有効にするには、OTEL_TRACES_EXPORTER/OTEL_METRICS_EXPORTER/OTEL_LOGS_EXPORTER 環境変数を otlp に設定します。

環境変数を使用して OTLP エクスポーターをカスタマイズするには、OTLP エクスポーターのドキュメントを参照してください。 重要な環境変数は以下の通りです。

[1]: OTEL_EXPORTER_OTLP_PROTOCOL に関する考慮事項:

• OpenTelemetry .NET 自動計装のデフォルトは http/protobuf であり、OpenTelemetry .NET SDK のデフォルト値 grpc とは異なります。
• .NET 8 以上では、grpc OTLP エクスポータープロトコルを使用するためにアプリケーションが Grpc.Net.Client を参照する必要があります。 たとえば、.csproj ファイルに <PackageReference Include="Grpc.Net.Client" Version="2.65.0" /> を追加します。
• .NET Framework では、grpc OTLP エクスポータープロトコルはサポートされていません。

[2]: OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE で認識される値（大文字小文字を区別しない）:

• Cumulative: すべての計装の種類に対して累積集約テンポラリティを選択します。
• Delta: Counter、Asynchronous Counter、Histogram の計装の種類に対して Delta 集約テンポラリティを選択し、UpDownCounter と Asynchronous UpDownCounter の計装の種類に対しては Cumulative 集約を選択します。
• LowMemory: この構成は、Synchronous Counter と Histogram に対して Delta 集約テンポラリティを使用し、Synchronous UpDownCounter、Asynchronous Counter、Asynchronous UpDownCounter の計装の種類に対しては Cumulative 集約テンポラリティを使用します。
  • ⚠️ 仕様で知られるこの値はサポートされていません。

[3]: mTLS（相互 TLS）構成に関する考慮事項:

• mTLS は .NET 8.0 以上でのみサポートされます。
• すべての証明書ファイルは PEM 形式である必要があります。
• mTLS を使用する場合、OTEL_EXPORTER_OTLP_ENDPOINT は https:// を使用する必要があります。
• mTLS は .NET Framework ではサポートされていません。

Prometheus

ステータス: Experimental

Prometheus エクスポーターを有効にするには、OTEL_METRICS_EXPORTER 環境変数を prometheus に設定します。

エクスポーターは http://localhost:9464/metrics でメトリクスの HTTP エンドポイントを公開し、レスポンスを 300 ミリ秒間キャッシュします。

詳細については、Prometheus Exporter HttpListener のドキュメントを参照してください。

Zipkin

ステータス: Stable

Zipkin エクスポーターを有効にするには、OTEL_TRACES_EXPORTER 環境変数を zipkin に設定します。

環境変数を使用して Zipkin エクスポーターをカスタマイズするには、Zipkin エクスポーターのドキュメントを参照してください。 重要な環境変数は以下の通りです。

追加設定

RuleEngine

RuleEngine は、OpenTelemetry API、SDK、Instrumentation、Exporter アセンブリをサポートされていないシナリオに対して検証する機能であり、クラッシュするかわりにバックオフすることで OpenTelemetry の自動計装をより安定させます。 .NET 8 以上で動作します。

RuleEngine は、アプリケーションの初回実行時、またはデプロイメントが変更されたか自動計装ライブラリがアップグレードされた場合にのみ有効にしてください。 一度検証されると、アプリケーションの再起動時にルールを再検証する必要はありません。

.NET CLR プロファイラー

CLR はプロファイラーのセットアップに以下の環境変数を使用します。 詳細については、.NET Runtime Profiler Loading を参照してください。

OpenTelemetry .NET 自動計装を .NET CLR プロファイラーとして設定することは、.NET Framework では必須です。

.NET では、.NET CLR プロファイラーはバイトコード計装にのみ使用されます。 ソース計装のみで十分な場合は、以下の環境変数を解除または削除できます。

COR_ENABLE_PROFILING
COR_PROFILER
COR_PROFILER_PATH_32
COR_PROFILER_PATH_64
CORECLR_ENABLE_PROFILING
CORECLR_PROFILER
CORECLR_PROFILER_PATH
CORECLR_PROFILER_PATH_32
CORECLR_PROFILER_PATH_64

.NET ランタイム

.NET では、.NET CLR プロファイラーが使用されない場合、DOTNET_STARTUP_HOOKS 環境変数を設定する必要があります。

DOTNET_ADDITIONAL_DEPS と DOTNET_SHARED_STORE 環境変数は、.NET でのアセンブリバージョンの競合を軽減するために使用されます。

.NET CLR プロファイラーが使用されており、DOTNET_STARTUP_HOOKS 環境変数が設定されていない場合、プロファイラーは OpenTelemetry.AutoInstrumentation.Native.dll ファイルの場所を基準に適切なディレクトリで OpenTelemetry.AutoInstrumentation.StartupHook.dll を探します。 フォルダー構造は ZIP アーカイブ構造または NuGet パッケージ構造（プラットフォーム依存またはプラットフォーム非依存）と一致させることができます。 スタートアップフックアセンブリが見つからない場合、プロファイラーの読み込みは中断されます。

内部ログ

内部ログのデフォルトのディレクトリパスは以下の通りです。

• Windows: %ProgramData%\OpenTelemetry .NET AutoInstrumentation\logs
• Linux: /var/log/opentelemetry/dotnet
• macOS: /var/log/opentelemetry/dotnet

デフォルトのログディレクトリを作成できない場合、計装は現在のユーザーの一時フォルダーのパスをかわりに使用します。