SolarWindsAPM.Agent NuGet package

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

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

2. Set the Service key in the solarwinds_apm.config file that is published as part of the SolarWindsAPM.Agent NuGet package. See SolarWindsAPM.Agent NuGet package for more information on the location of this file.

   Alternatively, the Service key can be set using the environment variable SW_APM_SERVICE_KEY.

3. After adding the NuGet package to your project, the automatic instrumentation starts traces and reports spans. Alternatively, you can use the ASP.NET middleware or SDK methods in your application to start traces and report spans and custom metrics.
4. All the files published in the SolarWindsAPM.Agent NuGet package must be deployed with your application.

The SolarWindsAPM.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.Agent package must be able to find and load the native shared library and its dependencies at runtime. The .NET Core runtime looks for the shared library in one of the following directories:

• For 64-bit applications on the Windows platform: <published-dotnet-core-app>\SolarWindsAPM\x64\
• For 32-bit applications on the Windows platform: <published-dotnet-core-app>\SolarWindsAPM\x86\
• On the Linux platform: <published-dotnet-core-app>/SolarWindsAPM/runtimes/linux-x64/native/
• On the Alpine platform: <published-dotnet-core-app>/SolarWindsAPM/runtimes/linux-musl-x64/native/

If the location of the runtime directory is changed, update the PATH environment variable for Windows platforms or the LD_LIBRARY_PATH environment variable for Linux platforms. 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 either at the system level or for the process that you would like to instrument.

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-core-app>\SolarWindsAPM
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}
CORECLR_PROFILER_PATH_32	<published-dotnet-core-app>\SolarWindsAPM\x86\solarwinds_apm_profiler.dll
CORECLR_PROFILER_PATH_64	<published-dotnet-core-app>\SolarWindsAPM\x64\solarwinds_apm_profiler.dll

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-core-app>/SolarWindsAPM
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}
Linux x64 CORECLR_PROFILER_PATH	<published-dotnet-core-app>/SolarWindsAPM/linux-x64/solarwinds_apm_profiler.so
Alpine x64 CORECLR_PROFILER_PATH	<published-dotnet-core-app>/SolarWindsAPM/linux-musl-x64/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.

Adding the SolarWindsAPM.Agent ASP.NET middleware

The .NET Core SDK included in the SolarWindsAPM.Agent NuGet package provides an ASP.NET Core middleware that can be added to your ASP.NET Core application to start traces and report metrics automatically.

The middleware is required only if you are not using the automatic instrumentation feature of the .NET Library.

To use it, add the line app.UseSolarWindsApm(); to the Startup.cs file in your ASP.NET Core project. See the following Startup.cs example:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Http;
using AppOptics.Instrumentation;

public class Startup
{
  public void Configure(IApplicationBuilder app)
  {
    app.UseSolarWindsApm(); // Add the AppOptics.Instrumentation middleware
    app.UseMvcWithDefaultRoute();
  }
}

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.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/DotNetAgentLog*
• Windows: C:\Windows\Temp\SolarWinds\DotNetAgentLog*

NuGet package compatibility with the Windows or Linux Library

The SolarWindsAPM.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, see SolarWindsAPM.Agent NuGet package.