OpenTelemetry .NET¶

OpenTelemetry .NET Automatic Instrumentation は、CLR Profiler と Startup Hook を使用して、実行時に SDK と計装ライブラリを読み込みます。ビジネスコードを変更することなく、サポートされている ASP.NET、HTTP クライアント、データベース、メッセージシステムなどの呼び出しを収集できます。

このドキュメントでは、DataKit の OpenTelemetry コレクターを使用して OTLP データを受信し、Guance に転送します。

.NET アプリ + OpenTelemetry .NET Automatic Instrumentation -> OTLP -> DataKit -> Guance

前提条件¶

マイクロソフトのサポート期間内にある .NET バージョンを使用していること。.NET Framework の最小サポートバージョンは 4.6.2 です。
サポートされている x86、x64、または ARM64 の実行環境を使用していること。ARM64 のサポートは実験段階です。
DataKit がインストールされており、DataKit が対象の Guance ワークスペースに接続されていること。
.NET アプリケーションから DataKit へのネットワークが到達可能であること。OTLP/HTTP は DataKit HTTP ポート 9529 を使用し、OTLP/gRPC はデフォルトで 4317 を使用します。

バージョンサポート¶

原文のバージョン互換性情報を保持し、現在の公式互換性声明を最終的な根拠とします。

.NET バージョン	関連する Automatic Instrumentation バージョン	説明
.NET 10	v1.13.0 以降	v1.13.0 で .NET 10 のサポートが明示的に追加されました。
.NET 9	v1.13.0 に適合	v1.13.0 で .NET 9 STS ライフサイクル関連のルールが更新されました。
.NET 8	v1.2.0 以降	v1.2.0 で .NET 8 のサポートが明示的に追加されました。
.NET 7	過去のバージョンでサポート	.NET 7 はマイクロソフトのサポートが終了しており、本番環境での使用は推奨されません。
.NET Framework 4.6.2+	一般的な互換性要件	4.6.2 は現在の自動インストルメンテーションがサポートする最小の .NET Framework バージョンです。

インストール時は、古い v1.2.0 モジュールアドレスを固定して使用せず、このドキュメントで提供されている releases/latest/download の公式アドレスを使用して最新バージョンを取得してください。アップグレード前に OpenTelemetry .NET Automatic Instrumentation Releases を確認し、テスト環境で対象アプリケーションと依存関係を検証することをお勧めします。

一、OpenTelemetry コレクターを有効にする¶

DataKit インストールディレクトリの conf.d/opentelemetry に移動します。コレクター設定がまだ作成されていない場合は、サンプルファイルをコピーします。

cd /usr/local/datakit/conf.d/opentelemetry
sudo cp opentelemetry.conf.sample opentelemetry.conf

opentelemetry.conf に、少なくとも以下の受信設定が含まれていることを確認します。

[[inputs.opentelemetry]]
  # Guance でタグとして保持するカスタム属性をホワイトリストに追加します。
  customer_tags = ["team", "project"]

  [inputs.opentelemetry.http]
    http_status_ok = 200
    trace_api = "/otel/v1/traces"
    metric_api = "/otel/v1/metrics"
    logs_api = "/otel/v1/logs"

  [inputs.opentelemetry.grpc]
    addr = "127.0.0.1:4317"
    max_payload = 16777216

受信アドレスは以下の通りです。

プロトコル	データタイプ	DataKit 受信アドレス
OTLP/HTTP + Protobuf	Trace	`http://<DataKit-IP>:9529/otel/v1/traces`
OTLP/HTTP + Protobuf	Metric	`http://<DataKit-IP>:9529/otel/v1/metrics`
OTLP/HTTP + Protobuf	Log	`http://<DataKit-IP>:9529/otel/v1/logs`
OTLP/gRPC	Trace、Metric、Log	`http://<DataKit-IP>:4317`

.NET アプリケーションと DataKit が同一ホスト上にない場合は、実際のデプロイに応じて DataKit のリスニングアドレス、ファイアウォール、またはその他のネットワークアクセス制御を調整する必要があります。gRPC の場合は、addr をアプリケーションがアクセス可能なリスニングアドレス（例: 0.0.0.0:4317）に変更できます。OTLP 受信ポートを公衆ネットワークに直接公開しないでください。

DataKit を再起動し、サービスを確認します。

sudo datakit service restart
curl http://127.0.0.1:9529/v1/ping

二、アプリケーションを OpenTelemetry に接続する¶

Linux および macOS¶

OpenTelemetry 公式 GitHub リリースから最新のインストールスクリプトをダウンロードして実行します。

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"

レポートパラメータを設定し、自動インストルメンテーションに必要な変数を現在のシェルに注入します。

export OTEL_SERVICE_NAME="order-service"
export OTEL_RESOURCE_ATTRIBUTES="env=prod,version=1.0.0,team=backend"

export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:9529/otel"
export OTEL_PROPAGATORS="tracecontext,baggage"

. "$HOME/.otel-dotnet-auto/instrument.sh"
./MyNetApp

dotnet を使用して DLL を起動する場合は、最後の行を次のように変更します。

dotnet MyNetApp.dll

instrument.sh は、現在のシェルとその子プロセスにのみ影響します。systemd、Supervisor、またはその他のプロセスマネージャーを使用するシナリオでは、サービス起動環境でこのスクリプトを読み込み、OTEL_* を設定してから、アプリケーションプロセスを完全に再起動する必要があります。

Windows PowerShell¶

管理者権限を持つ Windows PowerShell Desktop 5.1 を使用して実行します。PowerShell Core 6.0 以降は、現在インストールモジュールのサポート対象外です。

#Requires -PSEdition Desktop

$moduleUrl = "https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/releases/latest/download/OpenTelemetry.DotNet.Auto.psm1"
$downloadPath = Join-Path $env:TEMP "OpenTelemetry.DotNet.Auto.psm1"

Invoke-WebRequest -Uri $moduleUrl -OutFile $downloadPath -UseBasicParsing
Import-Module $downloadPath -Force
Install-OpenTelemetryCore

$env:OTEL_SERVICE_NAME = "order-service"
$env:OTEL_RESOURCE_ATTRIBUTES = "env=prod,version=1.0.0,team=backend"
$env:OTEL_TRACES_EXPORTER = "otlp"
$env:OTEL_METRICS_EXPORTER = "none"
$env:OTEL_LOGS_EXPORTER = "none"
$env:OTEL_EXPORTER_OTLP_PROTOCOL = "http/protobuf"
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:9529/otel"
$env:OTEL_PROPAGATORS = "tracecontext,baggage"

Register-OpenTelemetryForCurrentSession -OTelServiceName "order-service"
.\MyNetApp.exe

上記の変数は、現在の PowerShell セッションとそのセッションから起動された子プロセスにのみ影響し、実行中の Windows Service や IIS ワーカープロセスには自動的に影響しません。

Windows グローバル環境変数¶

原文では、複数のレポートパラメータを一貫して設定する必要がある専用ホストに適した、マシンレベルの環境変数方式が提供されています。以下のコマンドは OpenTelemetry データパラメータのみを設定し、Register-OpenTelemetryForCurrentSession、Register-OpenTelemetryForWindowsService、または Register-OpenTelemetryForIIS による対象プロセスへの自動インストルメンテーション登録を代替するものではありません。

管理者 PowerShell で実行してください。

[Environment]::SetEnvironmentVariable("OTEL_SERVICE_NAME", "order-service", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_RESOURCE_ATTRIBUTES", "env=prod,version=1.0.0,team=backend", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_TRACES_EXPORTER", "otlp", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_METRICS_EXPORTER", "none", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_LOGS_EXPORTER", "none", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_EXPORTER_OTLP_PROTOCOL", "http/protobuf", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_EXPORTER_OTLP_ENDPOINT", "http://127.0.0.1:9529/otel", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_LOG_LEVEL", "info", "Machine")
[Environment]::SetEnvironmentVariable("OTEL_DOTNET_AUTO_LOGGER", "file", "Machine")
[Environment]::SetEnvironmentVariable(
  "OTEL_DOTNET_AUTO_LOG_DIRECTORY",
  "C:\ProgramData\OpenTelemetry .NET AutoInstrumentation\logs",
  "Machine"
)

マシンレベルの変数を確認します。

$names = @(
  "OTEL_SERVICE_NAME",
  "OTEL_RESOURCE_ATTRIBUTES",
  "OTEL_TRACES_EXPORTER",
  "OTEL_METRICS_EXPORTER",
  "OTEL_LOGS_EXPORTER",
  "OTEL_EXPORTER_OTLP_PROTOCOL",
  "OTEL_EXPORTER_OTLP_ENDPOINT",
  "OTEL_LOG_LEVEL",
  "OTEL_DOTNET_AUTO_LOGGER",
  "OTEL_DOTNET_AUTO_LOG_DIRECTORY"
)

foreach ($name in $names) {
  "{0} = {1}" -f $name, [Environment]::GetEnvironmentVariable($name, "Machine")
}

マシンレベルの変数は、新しく起動されたプロセスのみによって読み取られます。設定後、対象の Windows Service、IIS Application Pool、または IIS を再起動する必要があります。

Restart-WebAppPool -Name "OrderAppPool"
# または、影響範囲を確認した上で IIS を再起動します
iisreset

マシンレベルの設定はホスト上の複数のプロセスに影響を与えるため、共有ホスト上でのデフォルトの方式としては推奨されません。優先的に、現在のセッション、指定された Windows Service、または指定された IIS Application Pool の設定方式を使用してください。

Windows Service¶

コアファイルのインストール後、公式モジュールを使用して特定のサービスを登録できます。

Import-Module $downloadPath -Force
Install-OpenTelemetryCore

Register-OpenTelemetryForWindowsService `
  -WindowsServiceName "OrderService" `
  -OTelServiceName "order-service"

Register-OpenTelemetryForWindowsService は対象サービスを再起動します。また、データレポートに必要な OTEL_* パラメータが該当の Windows Service のプロセス環境に存在することを確認する必要があります。パラメータを変更した後は、サービスを再度再起動してください。

IIS 上の ASP.NET Framework¶

以下の方法は、IIS でホストされている ASP.NET .NET Framework アプリケーションに適用されます。

Import-Module $downloadPath -Force
Install-OpenTelemetryCore
Register-OpenTelemetryForIIS

Register-OpenTelemetryForIIS は IIS を再起動します。一般的なレポートパラメータは、アプリケーションの Web.config に記述できます。

<configuration>
  <appSettings>
    <add key="OTEL_SERVICE_NAME" value="order-service" />
    <add key="OTEL_RESOURCE_ATTRIBUTES" value="env=prod,version=1.0.0,team=backend" />
    <add key="OTEL_TRACES_EXPORTER" value="otlp" />
    <add key="OTEL_METRICS_EXPORTER" value="none" />
    <add key="OTEL_LOGS_EXPORTER" value="none" />
    <add key="OTEL_EXPORTER_OTLP_PROTOCOL" value="http/protobuf" />
    <add key="OTEL_EXPORTER_OTLP_ENDPOINT" value="http://127.0.0.1:9529/otel" />
  </appSettings>
</configuration>

環境変数は App.config や Web.config よりも優先されます。同じ IIS Application Pool 内の複数の .NET Framework アプリケーションがワーカープロセスを共有する場合、最初に起動されたアプリケーションが、そのプロセスが使用する OpenTelemetry SDK の設定を決定します。独立したサービス名とレポートパラメータが必要な場合は、独立したアプリケーションプールを使用する必要があります。

IIS Application Pool の定点設定¶

原文では、applicationHost.config で特定の Application Pool に環境変数を直接設定する方法も提供されています。これは、一部のサイトのみを収集する場合に適しています。変更前にバックアップを作成してください。

C:\Windows\System32\inetsrv\config\applicationHost.config

<system.applicationHost> の下にある <applicationPools> を見つけ、対象のアプリケーションプールの <add> ノードに以下を追加します。

<applicationPools>
  <add name="OrderAppPool">
    <environmentVariables>
      <add name="OTEL_SERVICE_NAME" value="order-service" />
      <add name="OTEL_RESOURCE_ATTRIBUTES" value="env=prod,version=1.0.0,team=backend" />
      <add name="OTEL_TRACES_EXPORTER" value="otlp" />
      <add name="OTEL_METRICS_EXPORTER" value="none" />
      <add name="OTEL_LOGS_EXPORTER" value="none" />
      <add name="OTEL_EXPORTER_OTLP_PROTOCOL" value="http/protobuf" />
      <add name="OTEL_EXPORTER_OTLP_ENDPOINT" value="http://127.0.0.1:9529/otel" />
      <add name="OTEL_LOG_LEVEL" value="info" />
      <add name="OTEL_DOTNET_AUTO_LOGGER" value="file" />
      <add
        name="OTEL_DOTNET_AUTO_LOG_DIRECTORY"
        value="C:\ProgramData\OpenTelemetry .NET AutoInstrumentation\logs" />
    </environmentVariables>
  </add>
</applicationPools>

設定完了後、対象の Application Pool を再起動します。Application Pool レベルの環境変数は、同名のマシンレベル変数を上書きします。グローバル値を統一して使用したい場合は、アプリケーションプール内の同名の OTEL_* を削除するか、調整する必要があります。この設定もパラメータのスコープを担当するのみで、IIS の自動インストルメンテーションには、事前に Register-OpenTelemetryForIIS を実行する必要があります。

OTLP/gRPC の制限¶

.NET Automatic Instrumentation はデフォルトで http/protobuf を使用するため、前述の HTTP 設定を使用して DataKit に接続することをお勧めします。.NET Framework は OTLP/gRPC をサポートしていません。.NET 8 以降で gRPC を使用する場合、アプリケーションは互換性のある Grpc.Net.Client パッケージを参照する必要があるため、依存関係を完全に変更しない接続方法ではなくなります。

三、データレポートパラメータ¶

基本パラメータ¶

環境変数	説明	推奨値または例
`OTEL_SERVICE_NAME`	`service.name` を設定します。設定されていない場合、自動インストルメンテーションはアプリケーションに基づいて名前を生成します。	`order-service`。本番環境では明示的に設定することを推奨します。
`OTEL_RESOURCE_ATTRIBUTES`	リソース属性。カンマ区切りの `key=value` 形式。	`env=prod,version=1.0.0,team=backend`
`OTEL_TRACES_EXPORTER`	Trace のエクスポーター。	DataKit にレポートする場合は `otlp` に設定します。無効にする場合は `none` に設定します。
`OTEL_METRICS_EXPORTER`	Metric のエクスポーター。	メトリクスをレポートする必要がある場合は `otlp` に設定し、それ以外の場合は `none` に設定します。
`OTEL_LOGS_EXPORTER`	Log のエクスポーター。	ログをレポートする必要がある場合は `otlp` に設定し、それ以外の場合は `none` に設定します。
`OTEL_PROPAGATORS`	サービス間のコンテキスト伝播形式。	デフォルトは `tracecontext,baggage`。`b3`、`b3multi` もサポートしています。
`OTEL_SDK_DISABLED`	OpenTelemetry SDK を無効にします。	デフォルトは `false`。緊急時に無効にする場合は `true` に設定します。

service.name は Guance 内でのサービス帰属に使用されます。env と version も同時に設定し、環境とバージョンでフィルタリングできるようにすることをお勧めします。その他のカスタムリソース属性は、DataKit の customer_tags ホワイトリストに追加された後でのみタグとして保持されます。属性名の . は _ に変換されます。

.NET 自動インストルメンテーションパラメータ¶

環境変数	説明	デフォルト値または例
`OTEL_DOTNET_AUTO_TRACES_ENABLED`	自動 Trace パイプラインを有効にします。	デフォルトは `true`。
`OTEL_DOTNET_AUTO_METRICS_ENABLED`	自動 Metric パイプラインを有効にします。	デフォルトは `true`。exporter が `none` の場合でも、`false` に設定してさらに無効にできます。
`OTEL_DOTNET_AUTO_LOGS_ENABLED`	自動 Log パイプラインを有効にします。	デフォルトは `true`。OTLP Log を収集しない場合は `false` に設定できます。
`OTEL_DOTNET_AUTO_EXCLUDE_PROCESSES`	自動インストルメンテーションをロードしないプロセスを除外します。複数の実行可能ファイル名はカンマで区切ります。	`powershell.exe,ReservedProcess.exe`。対象アプリケーションをホストする `dotnet` プロセスは除外しないでください。
`OTEL_DOTNET_AUTO_RESOURCE_DETECTOR_ENABLED`	自動インストルメンテーションに組み込まれているリソース検出器を有効にします。	デフォルトは `true`。
`OTEL_DOTNET_AUTO_LOGGER`	自動インストルメンテーションの内部診断ログの出力方法。	デフォルトは `file`。`console`、`none` もサポートしています。
`OTEL_DOTNET_AUTO_LOG_DIRECTORY`	自動インストルメンテーションの内部ログディレクトリ。	Windows のデフォルトは `%ProgramData%` 下。Linux/macOS のデフォルトは `/var/log/opentelemetry/dotnet`。
`OTEL_LOG_LEVEL`	SDK および自動インストルメンテーションのログレベル。	デフォルトは `info`。トラブルシューティング時は一時的に `debug` を使用します。

ホスト上のすべての .NET プロセスを評価したと明確に判断できない限り、システムまたはユーザーレベルで CLR Profiler をグローバルに有効にしないでください。グローバルな注入は、dotnet CLI、PowerShell、またはその他の対象外サービスに影響を与える可能性があります。現在のセッション、指定された Windows Service、または指定された IIS シナリオの登録方法を優先的に使用してください。

OTLP パラメータ¶

環境変数	説明	推奨値または例
`OTEL_EXPORTER_OTLP_PROTOCOL`	すべてのシグナルの OTLP プロトコル。	自動インストルメンテーションのデフォルトは `http/protobuf`。明示的に設定することを推奨します。
`OTEL_EXPORTER_OTLP_ENDPOINT`	すべてのシグナルで共通のベースアドレス。	HTTP: `http://datakit-host:9529/otel`。
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Trace のみに使用されるアドレス。共通アドレスより優先されます。	`http://datakit-host:9529/otel/v1/traces`
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Metric のみに使用されるアドレス。共通アドレスより優先されます。	`http://datakit-host:9529/otel/v1/metrics`
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Log のみに使用されるアドレス。共通アドレスより優先されます。	`http://datakit-host:9529/otel/v1/logs`
`OTEL_EXPORTER_OTLP_HEADERS`	すべての OTLP リクエストに含まれるリクエストヘッダー。複数の値はカンマで区切ります。	`x-tenant=tenant-a`。DataKit の `expected_headers` と一致させる必要があります。
`OTEL_EXPORTER_OTLP_COMPRESSION`	OTLP リクエストの圧縮方式。	デフォルトは `none`。ホスト間でレポートする場合は `gzip` に設定できます。
`OTEL_EXPORTER_OTLP_TIMEOUT`	単一エクスポートのタイムアウト（ミリ秒）。	デフォルトは `10000`。

DataKit の OTLP/HTTP 収集は Protobuf のみをサポートしています。http/protobuf を使用し、http/json は使用しないでください。共通エンドポイントと特定のデータタイプのエンドポイントが両方存在する場合、特定のデータタイプの設定が優先されます。

サンプリングおよびバッチレポートパラメータ¶

環境変数	説明	デフォルト値または例
`OTEL_TRACES_SAMPLER`	Trace ヘッダーサンプラー。	デフォルトは `parentbased_always_on`。比率によるサンプリングには `parentbased_traceidratio` を使用します。
`OTEL_TRACES_SAMPLER_ARG`	サンプラーの引数。	`0.1` は、ルート Trace の 10% をサンプリングすることを意味します。
`OTEL_BSP_SCHEDULE_DELAY`	Span のバッチエクスポート間隔（ミリ秒）。	デフォルトは `5000`。
`OTEL_BSP_MAX_QUEUE_SIZE`	エクスポート待ちの Span キューの上限。	デフォルトは `2048`。
`OTEL_BSP_MAX_EXPORT_BATCH_SIZE`	1 バッチあたりの最大エクスポート Span 数。	デフォルトは `512`。
`OTEL_BSP_EXPORT_TIMEOUT`	Span のバッチエクスポートタイムアウト（ミリ秒）。	デフォルトは `30000`。
`OTEL_METRIC_EXPORT_INTERVAL`	Metric のエクスポート間隔（ミリ秒）。	OTLP exporter のデフォルトは `60000`。

本番環境では、トラフィックとデータ予算に基づいてサンプリングレートを設定する必要があります。アプリケーション側のヘッダーサンプリングと DataKit 側のサンプリングを同時に有効にすると、最終的な保持率は相乗的に低下するため、サンプリングの場所を統一して計画する必要があります。

接続の確認¶

サポートされている計装ライブラリによって処理されるアプリケーションルートにリクエストを送信し、DataKit ホストで受信ログを確認します。

curl http://127.0.0.1:8080/
sudo tail -f /usr/local/datakit/log/gin.log | grep '/otel/v1/'

/otel/v1/traces への POST リクエストが表示され、応答コードが 200 の場合、DataKit が Trace を受信したことを示します。次に、Guance の「APM > トレース」に移動し、service:order-service で検索します。

データがない場合は、インストールスクリプトが完了しているか、アプリケーションを起動した実際のプロセスが CLR Profiler と OTEL_* 環境変数を継承しているか、アプリケーションが使用するライブラリがサポートリストに含まれているか、OTLP エンドポイントに到達可能かを順に確認してください。一時的に OTEL_LOG_LEVEL=debug を設定し、自動インストルメンテーションの内部ログを確認することもできます。トラブルシューティングが完了したら、info に戻してください。

OpenTelemetry .NET¶

前提条件¶

バージョンサポート¶

一、OpenTelemetry コレクターを有効にする¶

二、アプリケーションを OpenTelemetry に接続する¶

Linux および macOS¶

Windows PowerShell¶

Windows グローバル環境変数¶

Windows Service¶

IIS 上の ASP.NET Framework¶

IIS Application Pool の定点設定¶

OTLP/gRPC の制限¶

三、データレポートパラメータ¶

基本パラメータ¶

.NET 自動インストルメンテーションパラメータ¶

OTLP パラメータ¶

サンプリングおよびバッチレポートパラメータ¶

接続の確認¶

参考¶

このページは役に立ちましたか？

OpenTelemetry .NET¶

前提条件¶

バージョンサポート¶

一、OpenTelemetry コレクターを有効にする¶

二、アプリケーションを OpenTelemetry に接続する¶

Linux および macOS¶

Windows PowerShell¶

Windows グローバル環境変数¶

Windows Service¶

IIS 上の ASP.NET Framework¶

IIS Application Pool の定点設定¶

OTLP/gRPC の制限¶

三、データレポートパラメータ¶

基本パラメータ¶

.NET 自動インストルメンテーションパラメータ¶

OTLP パラメータ¶

サンプリングおよびバッチレポートパラメータ¶

接続の確認¶

参考¶

このページは役に立ちましたか？ ×

このページは役に立ちましたか？