.NET ゼロコード計装

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

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

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

互換性

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

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

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

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

セットアップ

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

Linux と macOS

.sh スクリプトをダウンロード、検証して実行します。

# インストーラーをプライベートディレクトリにダウンロード
version="v1.17.0"
repository="open-telemetry/opentelemetry-dotnet-instrumentation"
release_workflow="$repository/.github/workflows/release.yml"
download_dir="$(mktemp -d "${TMPDIR:-/tmp}/otel-dotnet-auto-installer.XXXXXX")"
installer="$download_dir/otel-dotnet-auto-install.sh"
trap 'rm -rf "$download_dir"' 0

# ダウンロード、検証、実行を単一の条件付きチェーンで行い、
# ダウンロードや検証に失敗した場合はインストーラーの実行を防止する
curl -sSfL "https://github.com/$repository/releases/download/$version/otel-dotnet-auto-install.sh" -o "$installer" &&
  gh release verify-asset "$version" "$installer" --repo "$repository" &&
  gh attestation verify "$installer" \
    --repo "$repository" \
    --signer-workflow "$release_workflow" \
    --source-ref "refs/tags/$version" &&
  VERSION="$version" sh "$installer"

# 計装スクリプトの実行を有効化
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

エアギャップ環境では、アーカイブを転送する前に検証し、インストーラーのオンライン検証を明示的にスキップしてください。 アーカイブを直接指定するには以下を実行します。

SKIP_RELEASE_VERIFICATION=true LOCAL_PATH=<PATH_TO_ARCHIVE> sh ./otel-dotnet-auto-install.sh

または、ファイルが格納されたフォルダーを指定すると、インストールスクリプトが使用する正しいファイルを判別します。

SKIP_RELEASE_VERIFICATION=true DOWNLOAD_DIR=<PATH_TO_FOLDER_WITH_FILES> sh ./otel-dotnet-auto-install.sh

Windows (PowerShell)

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

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

$version = "v1.17.0"
$repository = "open-telemetry/opentelemetry-dotnet-instrumentation"
$release_workflow = "$repository/.github/workflows/release.yml"
$skip_release_verification = $false

# Program Files のアクセス制御で保護された一意のディレクトリを使用する
$program_files = [System.Environment]::GetFolderPath([System.Environment+SpecialFolder]::ProgramFiles)
$download_dir = Join-Path $program_files "OpenTelemetry .NET AutoInstrumentation Download $([System.Guid]::NewGuid().ToString("N"))"
$download_path = Join-Path $download_dir "OpenTelemetry.DotNet.Auto.psm1"
$module_url = "https://github.com/$repository/releases/download/$version/OpenTelemetry.DotNet.Auto.psm1"

New-Item -ItemType Directory -Path $download_dir -ErrorAction Stop | Out-Null

try {
    Invoke-WebRequest -Uri $module_url -OutFile $download_path -UseBasicParsing

    if ($skip_release_verification) {
        Write-Warning "Release verification is skipped. Downloaded PowerShell code and binaries will not be verified."
    }
    else {
        $github_cli = Get-Command gh.exe -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1
        if (-not $github_cli) {
            throw "The GitHub CLI ('gh') is required. Install it from https://cli.github.com/ or explicitly set `$skip_release_verification to `$true."
        }

        & $github_cli.Source release verify-asset $version $download_path --repo $repository
        if ($LASTEXITCODE -ne 0) {
            throw "GitHub release verification failed for the PowerShell module."
        }

        & $github_cli.Source attestation verify $download_path `
            --repo $repository `
            --signer-workflow $release_workflow `
            --source-ref "refs/tags/$version"
        if ($LASTEXITCODE -ne 0) {
            throw "GitHub artifact attestation verification failed for the PowerShell module."
        }
    }

    # 検証成功後にモジュールをインポートする
    Import-Module $download_path

    # 以前にダウンロードした Windows アーカイブからインストールするには、以下を追加:
    # -LocalPath "C:\Path\To\OpenTelemetry.zip"
    Install-OpenTelemetryCore -SkipReleaseVerification:$skip_release_verification -ErrorAction Stop

    # 検証済みモジュールを更新とアンインストール用にキャッシュする
    Copy-Item -LiteralPath $download_path -Destination (Get-OpenTelemetryInstallDirectory) -Force
}
finally {
    if (Test-Path -LiteralPath $download_dir) {
        Remove-Item -LiteralPath $download_dir -Force -Recurse
    }
}

# 現在の 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.config の appSettings で最も一般的な 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.config の appSettings で最も一般的な OTEL_ 設定(OTEL_SERVICE_NAME など)を構成できます。

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

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

詳細な構成

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

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

NuGet パッケージ

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

コンテナの計装

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

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

エージェントの構成

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

ログとトレースの相関

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_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

はじめに

5分以内にアプリケーションのテレメトリーを取得しましょう!

利用可能な計装

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

構成と設定

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

カスタムトレースとメトリクスの作成

.NET 自動計装を使用したカスタムトレースとメトリクス。

OpenTelemetry.AutoInstrumentation NuGet パッケージの使用

.NET 自動計装の問題のトラブルシューティング