Documentation forSolarWinds Observability

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 Core/5+ 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/

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

SW_APM_HOME_DOTNET <published-dotnet-core-app>\SolarWindsAPM
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

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, see Install for stand-alone, non-IIS applications.

For Linux

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

SW_APM_HOME_DOTNET <published-dotnet-core-app>/SolarWindsAPM
CORECLR_ENABLE_PROFILING 1
CORECLR_PROFILER {AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
CORECLR_PROFILER_PATH <published-dotnet-core-app>/SolarWindsAPM/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 Core/5+ 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 SolarWindsAPM.Instrumentation;

public class Startup
{
  public void Configure(IApplicationBuilder app)
  {
    app.UseSolarWindsApm(); // Add the SolarWindsAPM.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*