Getting Started
Get telemetry for your app in less than 5 minutes!
OpenTelemetry .NET 自動計装を使用すると、ソースコードを変更せずに .NET アプリケーションやサービスからトレースとメトリクスをオブザーバビリティバックエンドに送信できます。
サービスやアプリケーションのコードを計装する方法については、手動計装を参照してください。
OpenTelemetry .NET 自動計装は、.NET の公式にサポートされているすべてのオペレーティングシステムとバージョンで動作します。
.NET Framework のサポートされる最小バージョンは 4.6.2 です。
サポートされるプロセッサーアーキテクチャは以下のとおりです。
ARM64 ビルドは CentOS ベースのイメージをサポートしていません。
CI テストは以下のオペレーティングシステムに対して実行されています。
.NET アプリケーションを自動的に計装するには、お使いのオペレーティングシステム用のインストーラスクリプトをダウンロードして実行してください。
.sh スクリプトをダウンロードして実行します。
エアギャップ環境では、LOCAL_PATH 変数を使用してインストールファイルを直接指定します。
LOCAL_PATH=<PATH_TO_INSTALLER> sh ./otel-dotnet-auto-install.sh
または、DOWNLOAD_DIR を使用してファイルが格納されたフォルダーを指定すると、インストールスクリプトが使用する正しいファイルを判別します。
DOWNLOAD_DIR=<PATH_TO_FOLDER_WITH_FILES> sh ./otel-dotnet-auto-install.sh
# bash スクリプトをダウンロード
curl -sSfL https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/otel-dotnet-auto-install.sh -O
# コアファイルをインストール
sh ./otel-dotnet-auto-install.sh
# 計装スクリプトの実行を有効化
chmod +x $HOME/.otel-dotnet-auto/instrument.sh
# 現在のシェルセッション用に計装をセットアップ
. $HOME/.otel-dotnet-auto/instrument.sh
# 計装を有効にしてアプリケーションを実行
OTEL_SERVICE_NAME=myapp OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=staging,service.version=1.0.0 ./MyNetApp
Windows では、管理者として PowerShell モジュールを使用します。
Windows PowerShell Desktop (v5.1) が必要です。 PowerShell Core (v6.0+) を含む他のバージョンは、現時点ではサポートされていません。
# PowerShell 5.1 が必要です
#Requires -PSEdition Desktop
# モジュールをダウンロード
$module_url = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$download_path = Join-Path $env:temp "OpenTelemetry.DotNet.Auto.psm1"
Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing
# モジュールをインポートしてその関数を使用
Import-Module $download_path
# コアファイルをインストール(オンライン方式 vs オフライン方式)
Install-OpenTelemetryCore
Install-OpenTelemetryCore -LocalPath "C:\Path\To\OpenTelemetry.zip"
# 現在の PowerShell セッション用に計装をセットアップ
Register-OpenTelemetryForCurrentSession -OTelServiceName "MyServiceDisplayName"
# 計装を有効にしてアプリケーションを実行
.\MyNetApp.exe
# 以下のコマンドを呼び出すと使用方法を確認できます
# 利用可能なすべてのコマンドを一覧表示
Get-Command -Module OpenTelemetry.DotNet.Auto
# コマンドの使用方法を取得
Get-Help Install-OpenTelemetryCore -Detailed
OpenTelemetry.DotNet.Auto.psm1 PowerShell モジュールを使用して、Windows サービスの自動計装をセットアップします。
# モジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"
# コアファイルをインストール
Install-OpenTelemetryCore
# Windows サービスの計装をセットアップ
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"
Register-OpenTelemetryForWindowsService はサービスの再起動を実行します。
構成を変更した後は、Windows サービスを再起動することを忘れないでください。
PowerShell で Restart-Service -Name $WindowsServiceName -Force を実行すると再起動できます。
.NET Framework アプリケーションの場合、App.config の appSettings で最も一般的な OTEL_ 設定(OTEL_RESOURCE_ATTRIBUTES など)を構成できます。
別の方法として、Windows レジストリで Windows サービスの環境変数を設定することもできます。
指定した Windows サービス($svcName)のレジストリキーは以下の場所にあります。
HKLM\SYSTEM\CurrentControlSet\Services\$svcName
環境変数は REG_MULTI_SZ(複数行レジストリ値)の Environment で以下の形式で定義されます。
Var1=Value1
Var2=Value2
以下の手順は .NET Framework アプリケーションに適用されます。
OpenTelemetry.DotNet.Auto.psm1 PowerShell モジュールを使用して、IIS の自動計装をセットアップします。
# モジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"
# コアファイルをインストール
Install-OpenTelemetryCore
# IIS の計装をセットアップ
Register-OpenTelemetryForIIS
Register-OpenTelemetryForIIS は IIS の再起動を実行します。
以下の手順は .NET Framework アプリケーションに適用されます。
ASP.NET アプリケーションの場合、Web.config の appSettings で最も一般的な OTEL_ 設定(OTEL_SERVICE_NAME など)を構成できます。
サービス名が明示的に構成されていない場合、自動的に生成されます。
.NET Framework で IIS 上にホストされているアプリケーションの場合、SiteName\VirtualDirectoryPath(例: MySite\MyApp)が使用されます。
ASP.NET Core アプリケーションの場合、Web.config ファイルの <aspNetCore> ブロック内の <environmentVariable> 要素を使用して、環境変数で構成を設定できます。
構成を変更した後は、IIS を再起動することを忘れないでください。
iisreset.exe を実行すると再起動できます。
applicationHost.config に <environmentVariables> を追加して、特定のアプリケーションプールの環境変数を設定できます。
IIS にデプロイされたすべてのアプリケーションに共通の環境変数を設定するには、W3SVC と WAS Windows サービスの環境変数を設定することを検討してください。
IIS 10.0 より古いバージョンの場合、別のユーザーを作成し、その環境変数を設定して、アプリケーションプールのユーザーとして使用することを検討できます。
self-contained アプリケーションを NuGet パッケージを使用して計装できます。
詳細については、NuGet パッケージを参照してください。
Docker コンテナの計装例については、GitHub のサンプルを参照してください。
OpenTelemetry Operator for Kubernetes も使用できます。
構成オプションの全範囲については、構成と設定を参照してください。
OpenTelemetry .NET 自動計装が提供する自動ログ・トレース相関は、現在 Microsoft.Extensions.Logging を使用する .NET アプリケーションでのみ動作します。
詳細については、#2310 を参照してください。
OpenTelemetry .NET SDK は自動的にログをトレースデータに相関させます。
アクティブなトレースのコンテキスト内でログが出力されると、トレースコンテキストフィールドの TraceId、SpanId、TraceState が自動的に設定されます。
以下は、サンプルコンソールアプリケーションが生成するログです。
"logRecords": [
{
"timeUnixNano": "1679392614538226700",
"severityNumber": 9,
"severityText": "Information",
"body": {
"stringValue": "Success! Today is: {Date:MMMM dd, yyyy}"
},
"flags": 1,
"traceId": "21df288eada1ce4ace6c40f39a6d7ce1",
"spanId": "a80119e5a05fed5a"
}
]
詳細については、以下を参照してください。
OpenTelemetry .NET 自動計装は、さまざまなライブラリをサポートしています。 完全なリストについては、計装を参照してください。
アプリケーションからのテレメトリーを標準出力に直接表示するには、アプリケーションを起動する前に、以下の環境変数の値に console を追加してください。
OTEL_TRACES_EXPORTEROTEL_METRICS_EXPORTEROTEL_LOGS_EXPORTER一般的なトラブルシューティング手順と特定の問題の解決方法については、トラブルシューティングを参照してください。
アプリケーションやサービスに自動計装を構成した後は、カスタムトレースとメトリクスの送信や手動計装を追加してカスタムテレメトリーデータを収集することもできます。
Linux と macOS では、インストール手順は現在のシェルセッションにのみ影響するため、明示的なアンインストールは不要です。
Windows では、管理者として PowerShell モジュールを使用します。
Windows PowerShell Desktop (v5.1) が必要です。 PowerShell Core (v6.0+) を含む他のバージョンは、現時点ではサポートされていません。
# PowerShell 5.1 が必要です
#Requires -PSEdition Desktop
# 以前にインストールしたモジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"
# 以前に IIS を登録した場合、登録を解除
Unregister-OpenTelemetryForIIS
# 以前に Windows サービスを登録した場合、登録を解除
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"
# 最後に、OpenTelemetry 計装をアンインストール
Uninstall-OpenTelemetryCore
Get telemetry for your app in less than 5 minutes!
OpenTelemetry .NET 自動計装がサポートするライブラリ。
.NET の自動計装の構成と設定
Custom traces and metrics using .NET automatic instrumentation.
このページは役に立ちましたか?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!