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 アプリケーションを自動的にインストルメンテーションします。

You can install the .NET instrumentation manually or using the NuGet packages. The manual instructions include the option to use a guided setup. The NuGet packages are the best method for avoiding dependency version conflicts, but are not well-suited for instrumenting multiple applications running on the same machine. Review the pre-checks and the various installation procedures on this page to identify the best installation method for your application environment.

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:

  • You’re unable to add the NuGet packages to the application project. This can be the case when instrumenting a third-party application.

  • You can’t accommodate the increased disk use required by installing the NuGet packages separately for each instrumented application running on the same machine.

  • You need to instrument a legacy application that can’t be migrated to the SDK-style project. To verify whether your project is SDK style, see Identify the project format in the NuGet documentation.

If your scenario isn’t compatible with NuGet package installation, install the distribution manually. See 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. In a terminal, navigate to the root directory of your .NET application.

  2. Add the NuGet packages using the following command, replacing <project> with the .csproj file name:

    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.

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

The instrumentation procedure in the previous section produces launch scripts in the output folder of the build. The Windows script is splunk-launch.cmd and the Linux script is splunk-launch.sh. The script passes all the command-line parameters that you provide to the application. Use the following steps to run your instrumented application:

  1. Identify the launch script in your build output.

  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:

    • Using the executable:

      • 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:

  • You’re unable to add the NuGet packages to the application project. This can be the case when instrumenting a third-party application.

  • You can’t accommodate the increased disk use required by installing the NuGet packages separately for each instrumented application running on the same machine.

  • You need to instrument a legacy application that can’t be migrated to the SDK-style project. To verify whether your project is SDK style, see Identify the project format in the NuGet documentation.

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. Go to the Available integrations tab, or select Add Integration in the Deployed integrations tab.

    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.

警告

In .NET version 8, setting the DOTNET_EnableDiagnostics runtime environment variable to 0 deactivates all diagnostics including the CLR Profiler, which is required for launching the .NET instrumentation if you are not using .NET startup hooks. Make sure that DOTNET_EnableDiagnostics is set to 1. To limit diagnostics to only the CLR Profiler, use the following environment variable settings:

  • 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. Register the distribution according to the type of application you’re instrumenting:

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

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

    注釈

    This command instruments any applications launched in the same PowerShell session. It won’t instrument applications in a different PowerShell session.

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

This page was last updated on 2024年11月13日.