Docs » Splunk Observability Cloud でサポートされているインテグレーション » バックエンドアプリケーションをインストルメンテーションして、スパンを Splunk APM に送信する » Splunk Observability Cloud (OpenTelemetry) 用 .NET アプリケーションのインストルメンテーション » .NET アプリケーションを Splunk Observability Cloud (OpenTelemetry) にインストルメンテーションする

.NET アプリケーションを Splunk Observability Cloud (OpenTelemetry) にインストルメンテーションする 🔗

注釈

Due to changes in the upstream OpenTelemetry documentation, 「automatic instrumentation」 has been changed to 「zero-code instrumentation」. For more information, see Instrumentation methods for Splunk Observability Cloud.

Splunk Distribution of OpenTelemetry .NETは、.NET アプリケーション、.NET アプリケーションを実行している Windows サービス、IIS 上にデプロイされた ASP.NET アプリケーションを自動的にインストルメンテーションします。

.NETインストルメンテーションは、手動またはNuGetパッケージを使用してインストールできます。マニュアルの手順には、ガイド付きセットアップを使用するオプションが含まれています。NuGetパッケージは、依存関係のバージョンの競合を避けるための最良の方法ですが、同じマシン上で動作する複数のアプリケーションのインストルメンテーションには適していません。事前チェック と、このページのさまざまなインストール手順を確認して、アプリケーション環境に最適なインストール方法を特定してください。

NuGetパッケージを使ってOpenTelemetry .NETインストルメンテーションをインストールします。 🔗

You can deploy the Splunk Distribution of the OpenTelemetry .NET instrumentation automatically using the official NuGet packages. Your instrumented application project must support NuGet packages.

NuGet package installation considerations 🔗

The following scenarios are ideal for using the NuGet packages:

  • アプリケーションのビルドはコントロールできるが、アプリケーションを実行するマシンやコンテナはコントロールできません。

  • 自己完結型アプリケーションのインストルメンテーションを行っています。.NET ドキュメントの Publish self-contained を参照してください。

  • You want to facilitate developer experimentation with zero-code instrumentation through NuGet packages.

  • You need to solve version conflicts between the dependencies used by the application and the zero-code instrumentation.

Don’t use the NuGet packages if any of the following apply to your environment:

  • アプリケーションプロジェクトに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を手動でインストールする を参照してください。

注釈

For advanced configuration of the .NET zero-code instrumentation, such as changing trace propagation formats or changing the endpoint URLs, see Splunk Distribution of OpenTelemetry .NET を設定する.

NuGetパッケージを使用してアプリケーションをインストルメンテーションする 🔗

To automatically instrument your application using the NuGet packages, add the Splunk.OpenTelemetry.AutoInstrumentation package to your project.

  1. ターミナルで、.NETアプリケーションのルートディレクトリに移動します。

  2. 以下のコマンドを使用して、<project> を .csproj ファイル名に置き換えて、NuGetパッケージを追加します：

    dotnet add <project> package Splunk.OpenTelemetry.AutoInstrumentation --prerelease

ビルドが失敗し、不足しているインストルメンテーション・パッケージを追加するよう促されたら、インストルメンテーション・パッケージを追加するか、SkippedInstrumentation プロパティに追加して、リストされたパッケージのインストルメンテーションをスキップしてください。例:

<PropertyGroup>
   <SkippedInstrumentations>MongoDB.Driver.Core;StackExchange.Redis</SkippedInstrumentations>
</PropertyGroup>

Alternatively, you can set the SkippedInstrumentation property from the terminal. Rewrite the ; separator as %3B. For example:

dotnet build -p:SkippedInstrumentations=StackExchange.Redis%3BMongoDB.Driver.Core

To distribute the appropriate native runtime components with your .NET application, specify a Runtime Identifier (RID) to build the application using dotnet build or dotnet publish. For more information, see .NET RID Catalog in the .NET documentation.

Both self-contained and framework-dependent applications are compatible with zero-code instrumentation. See .NET application publishing overview in the .NET documentation for more information.

インストルメンテーションされたアプリケーションを実行する 🔗

前節のインストルメンテーション手順は、ビルドの出力フォルダに起動スクリプトを生成します。Windowsスクリプトは splunk-launch.cmd であり、Linuxスクリプトは splunk-launch.sh です。スクリプトは、アプリケーションに提供するすべてのコマンドラインパラメータを渡します。以下の手順を使用して、インストルメンテーションされたアプリケーションを実行します：

  1. ビルド出力で起動スクリプトを特定します。

  2. (Optional) If you want to view telemetry data output in your console to verify that instrumentation is working, add console to the value (for example OTEL_TRACES_EXPORTER=otlp,console) of the following environment variables:

    • OTEL_TRACES_EXPORTER

    • OTEL_METRICS_EXPORTER

    • OTEL_LOGS_EXPORTER

  3. Run the instrumented application using the launch script:

    • 実行ファイルを使う：

      • Windows: splunk-launch.cmd <application_executable>.

      • Linux: splunk-launch.sh <application_executable>.

    • Using the dotnet CLI:

      • Windows: splunk-launch.cmd dotnet <application>.

      • Linux: splunk-launch.sh dotnet <application>.

Splunk Distribution of OpenTelemetry .NETを手動でインストールする 🔗

You can deploy the Splunk Distribution of OpenTelemetry .NET instrumentation manually, using either the guided setup or the step-by-step instructions below.

Manual installation considerations 🔗

The following scenarios are ideal for manually installing the .NET instrumentation:

  • アプリケーションプロジェクトにNuGetパッケージを追加できません。これは、サードパーティのアプリケーションをインストルメンテーションする場合に起こり得ます。

  • 同じマシン上で動作するインストルメント済みアプリケーションごとにNuGetパッケージを個別にインストールすることで、ディスク使用量の増加に対応することはできません。

  • SDK形式のプロジェクトに移行できないレガシーアプリケーションをインストルメンテーションする必要があります。プロジェクトがSDKスタイルかどうかを確認するには、NuGetドキュメントの`Identify the project format<https://learn.microsoft.com/en-us/nuget/resources/check-project-format>`__を参照してください。

Consider using the NuGet packages if any of the following apply to your environment:

  • アプリケーションのビルドはコントロールできるが、アプリケーションを実行するマシンやコンテナはコントロールできません。

  • 自己完結型アプリケーションのインストルメンテーションを行っています。.NET ドキュメントの Publish self-contained を参照してください。

  • You want to facilitate developer experimentation with zero-code instrumentation through NuGet packages.

  • You need to solve version conflicts between the dependencies used by the application and the zero-code instrumentation.

公式NuGetパッケージを使用してディストリビューションをインストールするには、NuGetパッケージを使ってOpenTelemetry .NETインストルメンテーションをインストールします。 を参照してください。

注釈

For advanced configuration of the .NET zero-code instrumentation, such as changing trace propagation formats or changing the endpoint URLs, see Splunk Distribution of OpenTelemetry .NET を設定する.

ガイド付きセットアップを使用してカスタマイズされた指示を生成する 🔗

お使いの環境とアプリケーションの基本的なインストールコマンドをすべて生成するには、.NET OpenTelemetryガイド付きセットアップを使用します。.NET OpenTelemetryガイド付きセットアップにアクセスするには、以下の手順に従ってください：

  1. Splunk Observability Cloud にログインします。

  2. .NET OpenTelemetry ガイド付きセットアップ を開きます。オプションで、ガイド付きセットアップに自分で移動することもできます：

    1. ナビゲーションメニューで、Data Management を選択します。

    2. Available integrations タブにアクセスするか、Deployed integrations タブで Add Integration を選択します。

    3. インテグレーションフィルターメニューで、By Product を選択します。

    4. APM 製品を選択します。

    5. .NET (OpenTelemetry) タイルを選択し、.NET OpenTelemetry ガイド付きセットアップを開きます。

.NETアプリケーションのインストルメンテーション 🔗

ガイド付きセットアップを使用しない場合は、以下の手順に従って手動で Splunk Distribution of OpenTelemetry .NET をインストールしてください：

Use the following steps to automatically instrument your application.

警告

.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 🔗

  1. 条件を満たしているか確認してください。OpenTelemetry .NET インストルメンテーションの互換性と要件 を参照してください。

  2. (オプション）必要に応じて、SignalFx Instrumentation for .NETをアンインストールします。SignalFx Instrumentation for .NETをアンインストールします。 を参照してください。

  3. 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

  4. インストルメンテーションするアプリケーションの種類に応じて、ディストリビューションを登録します：

    # Set up environment to start instrumentation from the current PowerShell session
Register-OpenTelemetryForCurrentSession -OTelServiceName "<your-service-name>"

  5. 環境とサービスバージョンのリソース属性を設定します：

    # Configure environment and service version for current PowerShell session
$env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

    属性を設定したら、アプリケーションを実行します。

    注釈

    このコマンドは、同じPowerShellセッションで起動されたアプリケーションをインストルメンテーションします。別のPowerShellセッションのアプリケーションはインストルメンテーションしません。

APM にデータが表示されない場合は、Splunk Observability Cloud の .NET インストルメンテーションのトラブルシューティング を参照してください。

注釈

スパンにカスタム属性を追加する必要がある場合、またはスパンとメトリクスを手動で生成する場合は、.NET アプリケーションまたはサービスを手動でインストルメンテーションしてください。Splunk Observability Cloud 用に .NET アプリケーションを手動でインストルメンテーションする を参照してください。

Linux 🔗

  1. 条件を満たしているか確認してください。OpenTelemetry .NET インストルメンテーションの互換性と要件 を参照してください。

  2. (オプション）必要に応じて、SignalFx Instrumentation for .NETをアンインストールします。SignalFx Instrumentation for .NETをアンインストールします。 を参照してください。

  3. 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

  4. Activate the zero-code instrumentation:

    # Activate the zero-code instrumentation
. $HOME/.splunk-otel-dotnet/instrument.sh

  5. 環境とサービスバージョンのリソース属性を設定します：

    export OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

  6. アプリケーションを実行します。

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 設定 を参照してください。

インストルメンテーションの設定 🔗

For advanced configuration of the .NET zero-code instrumentation, like changing trace propagation formats or changing the endpoint URLs, see Splunk Distribution of OpenTelemetry .NET を設定する.

データベースクエリのパフォーマンス設定 🔗

バージョン 1.4.0 以降、.NET OTel インストルメンテーションは、データベースクエリパフォーマンスのためにデータベースクエリを収集します。Database Query Performanceの監視 を参照してください。

SQL文に機密情報が含まれている可能性があります。この動作を設定するには、インストルメンテーション設定 の OTEL_DOTNET_AUTO_SQLCLIENT_SET_DBSTATEMENT_FOR_TEXT と OTEL_DOTNET_AUTO_ENTITYFRAMEWORKCORE_SET_DBSTATEMENT_FOR_TEXT を参照してください。

Dockerコンテナ内で実行されているアプリケーションをインストルメンテーションする 🔗

Dockerコンテナ内で動作する.NETアプリケーションをインストルメンテーションするDockerfileの例は、GitHubの splunk/observability-content-contrib リポジトリにあります。

Azure Web Apps をインストルメンテーションする 🔗

Azure Web Apps 上で動作するアプリケーションやサービスをインストルメンテーションするには、Splunk Observability Cloud 用 .NET Azure Web App をインストルメンテーションする を参照してください。

Windows用オフラインインストール 🔗

To install the .NET zero-code instrumentation on Windows hosts that are offline, follow these steps:

  1. GitHub のReleases ページか ら以下のファイルをダウンロードし、オフライン・サーバーにコピーします：

    • Splunk.OTel.DotNet.psm1

    • splunk-opentelemetry-dotnet-windows.zip

  2. 以下のコマンドを実行して、PowerShellスクリプトを手動でインポートします：

    # Make sure the Download path is correct

Import-Module C:\Users\Administrator\Downloads\Splunk.OTel.DotNet.psm1

    プロンプトが表示されたら、Run Once に R を入力します。

  3. インストールコマンドを実行します：

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

アクセストークンを取得するには、Splunk Observability Cloudを使用したユーザー APIアクセストークンの取得と管理 を参照してください。

Splunk レルムを見つけるには、レルムに関する注意事項 を参照してください。

ソースホストの指定 🔗

エージェントが使用するホストを上書きするには、環境変数 OTEL_RESOURCE_ATTRIBUTES を使用して、ホストの名前を希望するソースに設定します：

$env: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

このページは 2024年12月09日 に最終更新されました。