SolarWindsAPM.OpenTelemetry.Agent NuGet package (Beta)

The .NET Library with OpenTelemetry support can be added to your project using the SolarWindsAPM.OpenTelemetry.Agent Nuget package. The NuGet package contains the .NET Library assemblies, some dependent libraries, and the solarwinds_apm.config file, which contains configuration options.

Use the NuGet package in the following scenarios:

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

2. Support instrumentation of self-contained applications. Note that self-contained single-file applications require additional setup.

To enable automatic instrumentation:

1. Add the SolarWindsAPM.OpenTelemetry.Agent NuGet package to your .NET 8+ project.

2. Set the Service key in the solarwinds_apm.config file that is published as part of the SolarWindsAPM.OpenTelemetry.Agent NuGet package. The file is published in the root folder of the published app. Alternatively, the Service key can be set using the environment variable SW_APM_SERVICE_KEY.

3. All the files published in the SolarWindsAPM.OpenTelemetry.Agent NuGet package must be deployed with your application.

4. Set the environment variables as described below. The required environment variables below are: SW_APM_HOME_DOTNET, CORECLR_ENABLE_PROFILING, CORECLR_PROFILER and profiler path (CORECLR_PROFILER_PATH, CORECLR_PROFILER_PATH_32 or CORECLR_PROFILER_PATH_64).

5. Enable OpenTelemetry support, OpenTelemetry must be enabled in the APM Library by using one of the following configuration settings:

   1. Set OpenTelemetry to Enabled in the solarwinds_apm.config file:

      1. <add key="OpenTelemetry" value="Enabled" />

   2. Set the SW_APM_OPEN_TELEMETRY environment variable to Enabled:

      1. SW_APM_OPEN_TELEMETRY=Enabled

6. After adding the NuGet package to your project and configuring the environment variables, the automatic instrumentation starts traces and reports spans.

The SolarWindsAPM.OpenTelemetry.Agent NuGet package contains a native shared library oboe_<major>_<minor>_<patch>.dll for Windows platforms and oboe_<major>_<minor>_<patch>.so for Linux platforms. The SolarWindsAPM.OpenTelemetry.Agent package must be able to find and load the native shared library and its dependencies at runtime. The .NET 8+ runtime looks for the shared library in either the application published folder or in one of the following directories:

• For published files where a target runtime was specified: <published-dotnet-app>

• For published files where a target runtime was not specified:

  • For 64-bit applications on the Windows platform: <published-dotnet-app>\runtimes\win-x64\native\

  • On the Linux platform: <published-dotnet-core-app>/runtimes/linux-x64/native/

  • On the Alpine platform: <published-dotnet-core-app>/runtimes/linux-musl-x64/native/

See Troubleshoot the .NET Library: Can the Linux SDK find and load the native shared library? for details.

Configuring automatic instrumentation

To configure the automatic instrumentation feature of the .NET Library, add the following environment variables for the process that you would like to instrument. The environment variables can also be set at a system level but that is not recommended.

For Windows

Environment variable	Environment variable value
SW_APM_SERVICE_KEY	(Optional) This overrides what is set in the solarwinds_apm.config file.  The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service. It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens. The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
SW_APM_HOME_DOTNET	<published-dotnet-app>
SW_APM_COLLECTOR	This overrides what is set for the ApmCollector key in the solarwinds_apm.config file. The SW_APM_COLLECTOR setting is optional and ensures the correct endpoint URI is used when sending data to the SolarWinds APM collector. To determine the correct endpoint for your SolarWinds APM collector, see Data centers and endpoint URIs.
CORECLR_ENABLE_PROFILING	1
CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
Target Runtime Not Selected:
CORECLR_PROFILER_PATH_64	<published-dotnet-app>\runtimes\win-x64\native\solarwinds_apm_profiler.dll
or Target Runtime Selected:
CORECLR_PROFILER_PATH	<published-dotnet-app>\solarwinds_apm_profiler.dll

All IIS (w3wp.exe) and dotnet.exe processes are instrumented automatically. If your application has a different process name, define the process name in the solarwinds_apm.config file. For information about configuring an application: for Windows, see Installation for stand-alone, non-IIS applications, and for Linux, see Instrumenting .NET 6+ executables.

For Linux and Alpine

Environment variable	Environment variable value
SW_APM_SERVICE_KEY	(Optional) This overrides what is set in the solarwinds_apm.config file.  The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service. It should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens. The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.
SW_APM_HOME_DOTNET	<published-dotnet-app>
SW_APM_COLLECTOR	This overrides what is set for the ApmCollector key in the solarwinds_apm.config file. The SW_APM_COLLECTOR setting is optional and ensures the correct endpoint URI is used when sending data to the SolarWinds APM collector. To determine the correct endpoint for your SolarWinds APM collector, see Data centers and endpoint URIs.
CORECLR_ENABLE_PROFILING	1
CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
Target Runtime Not Selected:
Linux x64 CORECLR_PROFILER_PATH	<published-dotnet-app>/runtimes/linux-x64/native/solarwinds_apm_profiler.so
Alpine x64 CORECLR_PROFILER_PATH	<published-dotnet-app>/runtimes/linux-musl-x64/native/solarwinds_apm_profiler.so
Linux arm64 CORECLR_PROFILER_PATH	<published-dotnet-app>/runtimes/linux-arm64/native/solarwinds_apm_profiler.so
Alpine arm64 CORECLR_PROFILER_PATH	<published-dotnet-app>/runtimes/linux-musl-arm64/native/solarwinds_apm_profiler.so
Target Runtime Selected:
CORECLR_PROFILER_PATH	<published-dotnet-app>/solarwinds_apm_profiler.so

Any application that starts with the dotnet command (runs under the dotnet process) is automatically considered for instrumentation. See Instrumenting .NET 6+ executables.

Troubleshooting

After you install the library, if traces and metric data do not appear in the Traces Explorer and Metrics Explorer, see Troubleshoot the .NET Library for resolution tips.

Log file locations

The SolarWindsAPM.OpenTelemetry.Agent NuGet package logs detailed information about problems it runs into, which can provide helpful information when troubleshooting. In a standard environment, the log files can be found in the following locations:

Linux: /var/tmp/solarwinds

Windows: C:\ProgramData\SolarWinds\APM\dotnet\logs

NuGet package compatibility with the Windows or Linux Library

The SolarWindsAPM.OpenTelemetry.Agent NuGet package can be added to an application that is deployed to a server where the Windows (SolarWindsAPM_DotNetAgent_Setup.exe) or Linux (tgz archive) APM library is installed. The location of the solarwinds_apm.config configuration file used by an application on the server depends on the environment variables set.