Docs » Instrument back-end applications to send spans to Splunk APM » Instrument .NET applications for Splunk Observability Cloud (OpenTelemetry) » Instrument your .NET application for Splunk Observability Cloud (OpenTelemetry)

Instrument your .NET application for Splunk Observability Cloud (OpenTelemetry) 🔗

The Splunk Distribution of OpenTelemetry .NET automatically instruments .NET applications, Windows services running .NET applications, and ASP.NET applications deployed on IIS.

To get started, use the guided setup, follow the instructions manually, or auto-instrument your application. See Splunk OpenTelemetry Zero Configuration Auto Instrumentation for .NET for more information.

Generate customized instructions using the guided setup 🔗

To generate all the basic installation commands for your environment and application, use the .NET OpenTelemetry guided setup. To access the .NET OpenTelemetry guided setup, follow these steps:

  1. Log in to Splunk Observability Cloud.

  2. Open the .NET OpenTelemetry guided setup . Optionally, you can navigate to the guided setup on your own:

    1. In the navigation menu, select Data Management.

    2. Select Add Integration to open the Integrate Your Data page.

    3. In the integration filter menu, select By Product.

    4. Select the APM product.

    5. Select the .NET (OpenTelemetry) tile to open the .NET OpenTelemetry guided setup.

Install the Splunk Distribution of OpenTelemetry .NET manually 🔗

Follow these instructions to install the Splunk Distribution of OpenTelemetry .NET:

To install the distribution using the official NuGet packages, see Install the OpenTelemetry .NET instrumentation using the NuGet packages.

Instrument your .NET application 🔗

Follow these steps to automatically instrument your application:

Windows 🔗

  1. Check that you meet the requirements. See OpenTelemetry .NET instrumentation compatibility and requirements.

  2. (Optional) If needed, uninstall the SignalFx Instrumentation for .NET. See Uninstall the SignalFx Instrumentation for .NET.

  3. Download and install the Splunk Distribution of OpenTelemetry .NET from the Releases page on GitHub . For example:

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

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

  5. Set the environment and service version resource attributes:

    # You can also set this in web.config or app.config
$env:OTEL_RESOURCE_ATTRIBUTES='deployment.environment=<envtype>,service.version=<version>'

  6. Run your application.

If no data appears in APM, see Troubleshoot .NET instrumentation for Splunk Observability Cloud.

Note

If you need to add custom attributes to spans or want to manually generate spans and metrics, instrument your .NET application or service manually. See Manually instrument .NET applications for Splunk Observability Cloud.

Linux 🔗

  1. Check that you meet the requirements. See OpenTelemetry .NET instrumentation compatibility and requirements.

  2. (Optional) If needed, uninstall the SignalFx Instrumentation for .NET. See Uninstall the SignalFx Instrumentation for .NET.

  3. Download and install the installation script of the Splunk Distribution of OpenTelemetry .NET from the Releases page on GitHub . For example:

    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 automatic instrumentation:

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

  5. Set the environment and service version resource attributes:

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

  6. Run your application.

If no data appears in APM, see Troubleshoot .NET instrumentation for Splunk Observability Cloud.

Note

If you need to add custom attributes to spans or want to manually generate spans, instrument your .NET application or service manually. See Manually instrument .NET applications for Splunk Observability Cloud.

Configure the instrumentation 🔗

For advanced configuration of the .NET automatic instrumentation, like changing trace propagation formats or changing the endpoint URLs, see Configure the Splunk Distribution of OpenTelemetry .NET.

Install the OpenTelemetry .NET instrumentation using the NuGet packages 🔗

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

Use the NuGet package in the following scenarios:

  1. You control the application build but not the machine or container where the application is running.

  2. You’re instrumenting a self-contained application. See Publish self-contained in the .NET documentation.

  3. You want to facilitate developer experimentation with automatic instrumentation through NuGet packages.

  4. You need to solve version conflicts between the dependencies used by the application and the automatic instrumentation.

Instrument your application using the NuGet packages 🔗

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

dotnet add [<PROJECT>] package Splunk.OpenTelemetry.AutoInstrumentation --prerelease

If the build fails and prompts you to add missing instrumentation packages, add the instrumentation package or skip the instrumentation of the listed package by adding it to the SkippedInstrumentation property. For example:

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

You can also 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.

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

Run the instrumented application 🔗

Use the script in the output folder of the build to run the application with automatic instrumentation activated.

  • On Windows, use splunk-launch.cmd <application_executable>.

  • On Linux, use splunk-launch.sh <application_executable>.

If you run the application using the dotnet CLI, add dotnet after the script.

  • On Windows, use splunk-launch.cmd dotnet <application>.

  • On Linux, use splunk-launch.sh dotnet <application>.

The script passes all the command-line parameters you provide to the application.

Offline installation for Windows 🔗

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

  1. Download the following files from the Releases page on GitHub and copy them to the offline server:

    • Splunk.OTel.DotNet.psm1

    • splunk-opentelemetry-dotnet-windows.zip

  2. Import the PowerShell script manually by running the following command:

    # Make sure the Download path is correct

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

    When prompted, enter R for Run Once.

  3. Run the install command:

    # Make sure the Download path is correct

Install-OpenTelemetryCore -LocalPath "C:\Users\Administrator\Downloads\splunk-opentelemetry-dotnet-windows.zip"

Send data directly to Splunk Observability Cloud 🔗

By default, all telemetry is sent to the local instance of the Splunk Distribution of OpenTelemetry Collector.

To bypass the OTel Collector and send data directly to Splunk Observability Cloud, set the following environment variables:

$env:SPLUNK_ACCESS_TOKEN=<access_token>
$env:SPLUNK_REALM=<realm>

To obtain an access token, see Retrieve and manage user API access tokens using Splunk Observability Cloud.

In the ingest endpoint URL, realm is the Splunk Observability Cloud realm, for example, us0. To find the realm name of your account, follow these steps:

  1. Open the navigation menu in Splunk Observability Cloud.

  2. Select Settings.

  3. Select your username.

The realm name appears in the Organizations section.

Uninstall the .NET instrumentation 🔗

To deactivate and uninstall the .NET instrumentation, run the following commands:

# Run the unregister command for your situation
Unregister-OpenTelemetryForIIS
Unregister-OpenTelemetryForWindowsService
Unregister-OpenTelemetryForCurrentSession

# Uninstall OpenTelemetry for .NET
Uninstall-OpenTelemetryCore