.NET ゼロコード計装

.NET アプリケーションとサービスからトレースとメトリクスを送信します。

OpenTelemetry .NET 自動計装を使用すると、ソースコードを変更せずに .NET アプリケーションやサービスからトレースとメトリクスをオブザーバビリティバックエンドに送信できます。

サービスやアプリケーションのコードを計装する方法については、手動計装を参照してください。

互換性

OpenTelemetry .NET 自動計装は、.NET の公式にサポートされているすべてのオペレーティングシステムとバージョンで動作します。

.NET Framework のサポートされる最小バージョンは 4.6.2 です。

サポートされるプロセッサーアーキテクチャは以下のとおりです。

CI テストは以下のオペレーティングシステムに対して実行されています。

セットアップ

.NET アプリケーションを自動的に計装するには、お使いのオペレーティングシステム用のインストーラスクリプトをダウンロードして実行してください。

Linux と macOS

.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 モジュールを使用します。

# 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

.NET アプリケーションを実行する Windows サービスの計装

OpenTelemetry.DotNet.Auto.psm1 PowerShell モジュールを使用して、Windows サービスの自動計装をセットアップします。

# モジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# コアファイルをインストール
Install-OpenTelemetryCore

# Windows サービスの計装をセットアップ
Register-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName" -OTelServiceName "MyServiceDisplayName"

Windows サービスの構成

.NET Framework アプリケーションの場合、App.configappSettings最も一般的な OTEL_ 設定OTEL_RESOURCE_ATTRIBUTES など)を構成できます。

別の方法として、Windows レジストリで Windows サービスの環境変数を設定することもできます。

指定した Windows サービス($svcName)のレジストリキーは以下の場所にあります。

HKLM\SYSTEM\CurrentControlSet\Services\$svcName

環境変数は REG_MULTI_SZ(複数行レジストリ値)の Environment で以下の形式で定義されます。

Var1=Value1
Var2=Value2

IIS にデプロイされた ASP.NET アプリケーションの計装

OpenTelemetry.DotNet.Auto.psm1 PowerShell モジュールを使用して、IIS の自動計装をセットアップします。

# モジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# コアファイルをインストール
Install-OpenTelemetryCore

# IIS の計装をセットアップ
Register-OpenTelemetryForIIS

ASP.NET アプリケーションの構成

ASP.NET アプリケーションの場合、Web.configappSettings最も一般的な OTEL_ 設定OTEL_SERVICE_NAME など)を構成できます。

サービス名が明示的に構成されていない場合、自動的に生成されます。 .NET Framework で IIS 上にホストされているアプリケーションの場合、SiteName\VirtualDirectoryPath(例: MySite\MyApp)が使用されます。

ASP.NET Core アプリケーションの場合、Web.config ファイルの <aspNetCore> ブロック内の <environmentVariable> 要素を使用して、環境変数で構成を設定できます。

詳細な構成

applicationHost.config<environmentVariables> を追加して、特定のアプリケーションプールの環境変数を設定できます。

IIS にデプロイされたすべてのアプリケーションに共通の環境変数を設定するには、W3SVCWAS Windows サービスの環境変数を設定することを検討してください。

NuGet パッケージ

self-contained アプリケーションを NuGet パッケージを使用して計装できます。 詳細については、NuGet パッケージを参照してください。

コンテナの計装

Docker コンテナの計装例については、GitHub のサンプルを参照してください。

OpenTelemetry Operator for Kubernetes も使用できます。

エージェントの構成

構成オプションの全範囲については、構成と設定を参照してください。

ログとトレースの相関

OpenTelemetry .NET SDK は自動的にログをトレースデータに相関させます。 アクティブなトレースのコンテキスト内でログが出力されると、トレースコンテキストフィールドTraceIdSpanIdTraceState が自動的に設定されます。

以下は、サンプルコンソールアプリケーションが生成するログです。

"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_EXPORTER
  • OTEL_METRICS_EXPORTER
  • OTEL_LOGS_EXPORTER

一般的なトラブルシューティング手順と特定の問題の解決方法については、トラブルシューティングを参照してください。

次のステップ

アプリケーションやサービスに自動計装を構成した後は、カスタムトレースとメトリクスの送信手動計装を追加してカスタムテレメトリーデータを収集することもできます。

アンインストール

Linux と macOS

Linux と macOS では、インストール手順は現在のシェルセッションにのみ影響するため、明示的なアンインストールは不要です。

Windows (PowerShell)

Windows では、管理者として PowerShell モジュールを使用します。

# PowerShell 5.1 が必要です
#Requires -PSEdition Desktop

# 以前にインストールしたモジュールをインポート
Import-Module "OpenTelemetry.DotNet.Auto.psm1"

# 以前に IIS を登録した場合、登録を解除
Unregister-OpenTelemetryForIIS

# 以前に Windows サービスを登録した場合、登録を解除
Unregister-OpenTelemetryForWindowsService -WindowsServiceName "WindowsServiceName"

# 最後に、OpenTelemetry 計装をアンインストール
Uninstall-OpenTelemetryCore

Getting Started

Get telemetry for your app in less than 5 minutes!

利用可能な計装

OpenTelemetry .NET 自動計装がサポートするライブラリ。

構成と設定

.NET の自動計装の構成と設定

Create custom traces and metrics

Custom traces and metrics using .NET automatic instrumentation.

Using the OpenTelemetry.AutoInstrumentation NuGet packages

Troubleshooting .NET automatic instrumentation issues