.NET アプリケーションを Splunk Observability Cloud (OpenTelemetry) にインストルメンテーションする 🔗
注釈
アップストリームのOpenTelemetryのドキュメントに変更があったため、「自動インストルメンテーション」は「ゼロコードインストルメンテーション」に変更されました。詳細は Splunk Observability Cloud のインストルメンテーションの方法 を参照してください。
Splunk Distribution of OpenTelemetry .NETは、.NET アプリケーション、.NET アプリケーションを実行している Windows サービス、IIS 上にデプロイされた ASP.NET アプリケーションを自動的にインストルメンテーションします。
.NETインストルメンテーションは、手動またはNuGetパッケージを使用してインストールできます。マニュアルの手順には、ガイド付きセットアップを使用するオプションが含まれています。NuGetパッケージは、依存関係のバージョンの競合を避けるための最良の方法ですが、同じマシン上で動作する複数のアプリケーションのインストルメンテーションには適していません。事前チェック と、このページのさまざまなインストール手順を確認して、アプリケーション環境に最適なインストール方法を特定してください。
NuGetパッケージを使ってOpenTelemetry .NETインストルメンテーションをインストールします。 🔗
Splunk Distribution of OpenTelemetry .NETは、公式NuGetパッケージを通じて自動的にデプロイできます。インストルメント済みアプリケーションのプロジェクトがNuGetパッケージをサポートしている必要があります。
NuGetパッケージのインストールに関する考慮事項 🔗
次のシナリオは、NuGetパッケージの使用に最適です。
アプリケーションのビルドはコントロールできるが、アプリケーションを実行するマシンやコンテナはコントロールできません。
自己完結型アプリケーションのインストルメンテーションを行っています。.NET ドキュメントの Publish self-contained を参照してください。
NuGetパッケージによるゼロコードインストルメンテーションで開発者の実験を容易にしたいと思っています。
アプリケーションで使用される依存関係とゼロコードインストルメンテーションの間のバージョンの競合を解決する必要があります。
以下のいずれかが使用環境に該当する場合は、NuGetパッケージを使用しないでください。
アプリケーションプロジェクトにNuGetパッケージを追加できません。これは、サードパーティのアプリケーションをインストルメンテーションする場合に起こり得ます。
同じマシン上で動作するインストルメント済みアプリケーションごとにNuGetパッケージを個別にインストールすることで、ディスク使用量の増加に対応することはできません。
SDK形式のプロジェクトに移行できないレガシーアプリケーションをインストルメンテーションする必要があります。プロジェクトがSDKスタイルかどうかを確認するには、NuGetドキュメントの`Identify the project format<https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__を参照してください。
シナリオがNuGetパッケージのインストールに対応していない場合は、ディストリビューションを手動でインストールしてください。Splunk Distribution of OpenTelemetry .NETを手動でインストールする を参照してください。
注釈
トレース伝播フォーマットの変更やエンドポイントURLの変更など、.NET ゼロコードインストルメンテーションの高度な設定については、Splunk Distribution of OpenTelemetry .NET を設定する を参照してください。
NuGetパッケージを使用してアプリケーションをインストルメンテーションする 🔗
NuGetパッケージを使用してアプリケーションを自動的にインストルメンテーションするには、Splunk.OpenTelemetry.AutoInstrumentation
パッケージをプロジェクトに追加します。
ターミナルで、.NETアプリケーションのルートディレクトリに移動します。
以下のコマンドを使用して、
<project>
を.csproj
ファイル名に置き換えて、NuGetパッケージを追加します:dotnet add <project> package Splunk.OpenTelemetry.AutoInstrumentation --prerelease
ビルドが失敗し、不足しているインストルメンテーション・パッケージを追加するよう促されたら、インストルメンテーション・パッケージを追加するか、SkippedInstrumentation
プロパティに追加して、リストされたパッケージのインストルメンテーションをスキップしてください。例:
<PropertyGroup>
<SkippedInstrumentations>MongoDB.Driver.Core;StackExchange.Redis</SkippedInstrumentations>
</PropertyGroup>
または、ターミナルから SkippedInstrumentation
プロパティを設定することもできます。;
のセパレーターを %3B
のように書き換えてください。例:
dotnet build -p:SkippedInstrumentations=StackExchange.Redis%3BMongoDB.Driver.Core
適切なネイティブランタイムコンポーネントを.NETアプリケーションと一緒に配布するには、dotnet build
または dotnet publish
を使用してアプリケーションをビルドするために、ランタイム識別子(RID)を指定します。詳細については、.NETドキュメントの .NET RIDカタログ を参照してください。
自己完結型アプリケーションとフレームワーク依存型アプリケーションの両方が、ゼロコードインストルメンテーションに対応しています。詳細は、.NETドキュメントの .NETアプリケーション公開の概要 を参照してください。
インストルメンテーションされたアプリケーションを実行する 🔗
前節のインストルメンテーション手順は、ビルドの出力フォルダに起動スクリプトを生成します。Windowsスクリプトは splunk-launch.cmd
であり、Linuxスクリプトは splunk-launch.sh
です。スクリプトは、アプリケーションに提供するすべてのコマンドラインパラメータを渡します。以下の手順を使用して、インストルメンテーションされたアプリケーションを実行します:
ビルド出力で起動スクリプトを特定します。
(オプション)コンソールでテレメトリデータ出力を表示し、インストルメンテーションが機能していることを確認したい場合は、以下の環境変数の値(例えば
OTEL_TRACES_EXPORTER=otlp,console
)にconsole
を追加します:OTEL_TRACES_EXPORTER
OTEL_METRICS_EXPORTER
OTEL_LOGS_EXPORTER
起動スクリプトを使用してインストルメント済みアプリケーションを実行します。
実行ファイルを使う:
Windows:
splunk-launch.cmd <application_executable>
。Linux:
splunk-launch.sh <application_executable>
。
dotnet
CLIの使用:Windows:
splunk-launch.cmd dotnet <application>
。Linux:
splunk-launch.sh dotnet <application>
。
Splunk Distribution of OpenTelemetry .NETを手動でインストールする 🔗
Splunk Distribution of OpenTelemetry .NETインストルメンテーションは、ガイド付きセットアップまたは下のステップバイステップの手順を使用して、手動でデプロイできます。
手動インストールに関する考慮事項 🔗
以下のシナリオは、.NETインストルメンテーションを手動でインストールするのに最適です。
アプリケーションプロジェクトにNuGetパッケージを追加できません。これは、サードパーティのアプリケーションをインストルメンテーションする場合に起こり得ます。
同じマシン上で動作するインストルメント済みアプリケーションごとにNuGetパッケージを個別にインストールすることで、ディスク使用量の増加に対応することはできません。
SDK形式のプロジェクトに移行できないレガシーアプリケーションをインストルメンテーションする必要があります。プロジェクトがSDKスタイルかどうかを確認するには、NuGetドキュメントの`Identify the project format<https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__を参照してください。
以下のいずれかが使用環境に該当する場合は、NuGetパッケージの使用を検討してください。
アプリケーションのビルドはコントロールできるが、アプリケーションを実行するマシンやコンテナはコントロールできません。
自己完結型アプリケーションのインストルメンテーションを行っています。.NET ドキュメントの Publish self-contained を参照してください。
NuGetパッケージによるゼロコードインストルメンテーションで開発者の実験を容易にしたいと思っています。
アプリケーションで使用される依存関係とゼロコードインストルメンテーションの間のバージョンの競合を解決する必要があります。
公式NuGetパッケージを使用してディストリビューションをインストールするには、NuGetパッケージを使ってOpenTelemetry .NETインストルメンテーションをインストールします。 を参照してください。
注釈
トレース伝播フォーマットの変更やエンドポイントURLの変更など、.NET ゼロコードインストルメンテーションの高度な設定については、Splunk Distribution of OpenTelemetry .NET を設定する を参照してください。
ガイド付きセットアップを使用してカスタマイズされた指示を生成する 🔗
お使いの環境とアプリケーションの基本的なインストールコマンドをすべて生成するには、.NET OpenTelemetryガイド付きセットアップを使用します。.NET OpenTelemetryガイド付きセットアップにアクセスするには、以下の手順に従ってください:
Splunk Observability Cloud にログインします。
.NET OpenTelemetry ガイド付きセットアップ を開きます。オプションで、ガイド付きセットアップに自分で移動することもできます:
ナビゲーションメニューで、
を選択します。Available integrations タブにアクセスするか、Deployed integrations タブで Add Integration を選択します。
インテグレーションフィルターメニューで、By Product を選択します。
APM 製品を選択します。
.NET (OpenTelemetry) タイルを選択し、.NET OpenTelemetry ガイド付きセットアップを開きます。
.NETアプリケーションのインストルメンテーション 🔗
ガイド付きセットアップを使用しない場合は、以下の手順に従って手動で Splunk Distribution of OpenTelemetry .NET をインストールしてください:
以下の手順を使用して、アプリケーションを自動的にインストルメンテーションしてください:
警告
.NET バージョン8では、ランタイム環境変数 DOTNET_EnableDiagnostics
を 0
に設定すると、.NET スタートアップフックを使用していない場合に.NETインストルメンテーションを起動するために必要なCLRプロファイラーを含むすべての診断が無効になります。 DOTNET_EnableDiagnostics
が 1
に設定されていることを確認してください。診断をCLR Profilerのみに制限するには、以下の環境変数設定を使用します:
DOTNET_EnableDiagnostics=1
DOTNET_EnableDiagnostics_Profiler=1
DOTNET_EnableDiagnostics_IPC=0
DOTNET_EnableDiagnostics_Debugger=0
Windows 🔗
条件を満たしているか確認してください。OpenTelemetry .NET インストルメンテーションの互換性と要件 を参照してください。
GitHub のReleases ページか ら Splunk Distribution of OpenTelemetry .NET をダウンロードしてインストールします。例えば
# Download and import the PowerShell module $module_url = "https://github.com/signalfx/splunk-otel-dotnet/releases/latest/download/Splunk.OTel.DotNet.psm1" $download_path = Join-Path $env:temp "Splunk.OTel.DotNet.psm1" Invoke-WebRequest -Uri $module_url -OutFile $download_path Import-Module $download_path # Install the Splunk distribution using the PowerShell module Install-OpenTelemetryCore
インストルメンテーションするアプリケーションの種類に応じて、ディストリビューションを登録します:
# Set up environment to start instrumentation from the current PowerShell session Register-OpenTelemetryForCurrentSession -OTelServiceName "<your-service-name>"
# Set up IIS instrumentation # IIS is restarted as a result Register-OpenTelemetryForIIS
# Set up your Windows Service instrumentation Register-OpenTelemetryForWindowsService -WindowsServiceName "<your-windows-service-name>" -OTelServiceName "<your-OTel-service-name>"
環境とサービスバージョンのリソース属性を設定します:
# Configure environment and service version for current PowerShell session $env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
属性を設定したら、アプリケーションを実行します。
注釈
このコマンドは、同じPowerShellセッションで起動されたアプリケーションをインストルメンテーションします。別のPowerShellセッションのアプリケーションはインストルメンテーションしません。
ASP.NETアプリケーションの場合は、web.configファイルの
appSettings
ブロックでサービス名とリソース属性を設定します:<appSettings> <add key="OTEL_SERVICE_NAME" value="my-service-name" /> <add key="OTEL_RESOURCE_ATTRIBUTES" value="deployment.environment=test,service.version=1.0.0" /> </appSettings>
注釈
IISでホストされているウェブアプリケーションに
OTEL_SERVICE_NAME
が設定されていない場合、サイト名と仮想ディレクトリパスに基づく推測名が使用されます。注釈
複数のアプリケーションが同じIISアプリケーションプールで実行されている場合、web.configファイルの
appSettings
ブロックを使用して環境変数を設定しないでください。インストルメンテーションに名前を推定させ、後述のアプリケーションプール環境変数設定を使用してリソース属性(アプリケーションプール内のすべてのアプリケーションで共有される)を設定します。web.configファイルを変更したら、IISを再起動します:
Start-Process "iisreset.exe" -NoNewWindow -Wait
注釈
高度なIISアプリケーション設定オプションについては、IISアプリケーションの高度な設定 を参照してください。
IIS でホストされている ASP.NET Core アプリケーションの場合、サービス名とリソース属性は :new-page:` web.config ファイル <https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/iis/web-config?view=aspnetcore-8.0#set-environment-variables>` の
environmentVariables
ブロックを使用して設定できます。例:<environmentVariables> <environmentVariable name="OTEL_SERVICE_NAME" value="my-service-name" /> <environmentVariable name="OTEL_RESOURCE_ATTRIBUTES" value="deployment.environment=test,service.version=1.0.0" /> </environmentVariables>
web.config
ファイルを修正したら、IIS を再起動します:Start-Process "iisreset.exe" -NoNewWindow -Wait
注釈
高度なIISアプリケーション設定オプションについては、IISアプリケーションの高度な設定 を参照してください。
.NET Frameworkアプリケーションでは、app.configファイルの
appSettings
ブロックでリソース属性を設定できます。<appSettings> <add key="OTEL_RESOURCE_ATTRIBUTES" value="deployment.environment=test,service.version=1.0.0" /> </appSettings>
また、各WindowsサービスのWindowsレジストリの
Environment
キーを変更することもできます。app.configファイルまたはWindowsレジストリを変更した後、サービスを再起動します:
Restart-Service -Name "<your-windows-service-name>" -Force
APM にデータが表示されない場合は、Splunk Observability Cloud の .NET インストルメンテーションのトラブルシューティング を参照してください。
注釈
スパンにカスタム属性を追加する必要がある場合、またはスパンとメトリクスを手動で生成する場合は、.NET アプリケーションまたはサービスを手動でインストルメンテーションしてください。Splunk Observability Cloud 用に .NET アプリケーションを手動でインストルメンテーションする を参照してください。
Linux 🔗
条件を満たしているか確認してください。OpenTelemetry .NET インストルメンテーションの互換性と要件 を参照してください。
GitHub のReleases ページか ら、Splunk Distribution of OpenTelemetry .NET のインストールスクリプトをダウンロードしてインストールします。例えば
curl -sSfL https://github.com/signalfx/splunk-otel-dotnet/releases/latest/download/splunk-otel-dotnet-install.sh -O # Install the distribution sh ./splunk-otel-dotnet-install.sh
ゼロコードインストルメンテーションの有効化:
# Activate the zero-code instrumentation . $HOME/.splunk-otel-dotnet/instrument.sh
環境とサービスバージョンのリソース属性を設定します:
export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'
アプリケーションを実行します。
APM にデータが表示されない場合は、Splunk Observability Cloud の .NET インストルメンテーションのトラブルシューティング を参照してください。
注釈
スパンにカスタム属性を追加する必要がある場合、またはスパンを手動で生成する場合は、.NETアプリケーションまたはサービスを手動でインストルメンテーションしてください。Splunk Observability Cloud 用に .NET アプリケーションを手動でインストルメンテーションする を参照してください。
AlwaysOn Profilingの有効化 🔗
AlwaysOn Profiling を有効にするには、 SPLUNK_PROFILER_ENABLED
環境変数 を true
に設定します。
メモリプロファイリングを有効にするには、AlwaysOn Profilingを有効にした後、SPLUNK_PROFILER_MEMORY_ENABLED
環境変数を true
に設定します。
詳細は Splunk APMのAlwaysOn Profilingにデータを取り込む を参照してください。その他の設定については、AlwaysOn Profiling の .NET OTel 設定 を参照してください。
インストルメンテーションの設定 🔗
トレース伝播フォーマットの変更やエンドポイント URL の変更など、.NET ゼロコードインストルメンテーションの高度な設定については、Splunk Distribution of OpenTelemetry .NET を設定する を参照してください。
データベースクエリのパフォーマンス設定 🔗
バージョン 1.4.0 以降、.NET OTel インストルメンテーションは、データベースクエリパフォーマンスのためにデータベースクエリを収集します。Database Query Performanceの監視 を参照してください。
SQL statements might contain sensitive information. To configure this behavior, use the following settings as described in OpenTelemetry .NET インストルメンテーションの互換性と要件.
OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT
OTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT
OTEL_DOTNET_AUTO_ORACLEMDA_SET_DBSTATEMENT_FOR_TEXT
For more details on enabling Database Query Performance, visit Database Query Performanceを有効にする.
Dockerコンテナ内で実行されているアプリケーションをインストルメンテーションする 🔗
Dockerコンテナ内で動作する.NETアプリケーションをインストルメンテーションするDockerfileの例は、GitHubの splunk/observability-content-contrib リポジトリにあります。
Azure Web Apps をインストルメンテーションする 🔗
Azure Web Apps 上で動作するアプリケーションやサービスをインストルメンテーションするには、Splunk Observability Cloud 用 .NET Azure Web App をインストルメンテーションする を参照してください。
Windows用オフラインインストール 🔗
オフラインのWindowsホストに.NET ゼロコードインストルメンテーションをインストールするには、以下の手順に従ってください:
GitHub のReleases ページか ら以下のファイルをダウンロードし、オフライン・サーバーにコピーします:
Splunk.OTel.DotNet.psm1
splunk-opentelemetry-dotnet-windows.zip
以下のコマンドを実行して、PowerShellスクリプトを手動でインポートします:
# Make sure the Download path is correct Import-Module C:\Users\Administrator\Downloads\Splunk.OTel.DotNet.psm1
プロンプトが表示されたら、
Run Once
にR
を入力します。インストールコマンドを実行します:
# Make sure the Download path is correct Install-OpenTelemetryCore -LocalPath "C:\Users\Administrator\Downloads\splunk-opentelemetry-dotnet-windows.zip"
Splunk Observability Cloud に直接データを送信する 🔗
デフォルトでは、すべてのテレメトリは Splunk Distribution of OpenTelemetry Collector のローカルインスタンスに送信されます。
OTel Collector をバイパスして Splunk Observability Cloud に直接データを送信するには、以下の環境変数を設定します:
$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:SPLUNK_REALM=<realm>
export SPLUNK_ACCESS_TOKEN=<access_token>
export SPLUNK_REALM=<realm>
アクセストークンを取得するには、Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理 を参照してください。
Splunk レルムを見つけるには、レルムに関する注意事項 を参照してください。
ソースホストの指定 🔗
エージェントが使用するホストを上書きするには、環境変数 OTEL_RESOURCE_ATTRIBUTES
を使用して、ホストの名前を希望するソースに設定します:
$env:OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>
export OTEL_RESOURCE_ATTRIBUTES=host.name=<host_name>
.NETインストルメンテーションをアンインストールする 🔗
.NETインストルメンテーションを無効にしてアンインストールするには、以下のコマンドを実行します:
# Run the unregister command for your situation
Unregister-OpenTelemetryForIIS
Unregister-OpenTelemetryForWindowsService
Unregister-OpenTelemetryForCurrentSession
# Uninstall OpenTelemetry for .NET
Uninstall-OpenTelemetryCore
rm -rf <path_of_otel_dotnet_install>