AppOptics.Agent NuGet package (legacy agent)

The following content pertains to NuGet package installation for the legacy AppOptics NET Agent.

AppOptics agents are no long receiving updates. The new SolarWinds Observability libraries can send APM data in AppOptics and are regularly updated with new features and improvements. If you are still relying on the AppOptics agents and your components are supported by the new libraries, consider transitioning to the SolarWinds Observability libraries for your APM needs. For more information about the benefits of migrating to the SolarWinds Observability libraries. Alternatively, you can use SolarWinds Observability as your primary APM solution.

If you have already transitioned to the new SolarWinds Observability NET Library, see the SolarWinds NET Library documentation for NuGet package installation information.

SolarWinds Observability libraries are not compatible with AppOptics agents. Do not use a mix of SolarWinds Observability libraries and AppOptics agents to instrument applications that are part of a distributed trace.

The .NET Agent and SDK can be added to your project using the AppOptics.Agent NuGet package. The NuGet package contains the .NET Agent assemblies, some dependent libraries and the agent.config file that contains configuration options.

Add the AppOptics.Agent NuGet package to your .NET Core/5+ project.
Set the ServiceKey in the agent.config file that is published as part of the AppOptics.Agent NuGet package. See AppOptics.Agent NuGet Package configuration for more information on the location of this file.

Alternatively, the service key can be set using the environment variable APPOPTICS_SERVICE_KEY.
After adding the NuGet package to your project you can use the automatic .NET Agent, ASP.NET middleware or SDK methods in your application to start traces, and report spans and custom metrics.
All the files published in the AppOptics.Agent NuGet package must be deployed with your application.

The AppOptics.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 AppOptics.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>/AppOptics/x64/
For 32-bit applications on the Windows platform: <published-dotnet-core-app>/AppOptics/x86/
On the Linux platform: <published-dotnet-core-app>/AppOptics/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 Troubleshooting (legacy agent): 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 Agent 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
`APPOPTICS_SERVICE_KEY`	(Optional) The service key which should be in the `<appoptics-api-token:service-name>` format. This overrides what is set in the `agent.config` file.
`APPOPTICS_HOME_APM_DOTNET`	`<published-dotnet-core-app>\AppOptics`
`CORECLR_ENABLE_PROFILING`	1
`CORECLR_PROFILER`	`{824293AD-22E2-4DAA-BC28-166C140543BE}`
`CORECLR_PROFILER_PATH_32`	`<published-dotnet-core-app>\AppOptics\x86\AppOpticsProfiler.dll`
`CORECLR_PROFILER_PATH_64`	`<published-dotnet-core-app>\AppOptics\x64\AppOpticsProfiler.dll`

All IIS (w3wp.exe) and dotnet.exe processes will be instrumented automatically. If your application has a different process name, define the process name in the agent.config file. For information about configuring an application, see instrumenting Non-IIS Applications.

For Linux

Environment Variable	Environment Variable Value
`APPOPTICS_SERVICE_KEY`	(Optional) The service key which should be in the `<appoptics-api-token:service-name>` format. This overrides what is set in the `agent.config` file.
`APPOPTICS_HOME_APM_DOTNET`	`<published-dotnet-core-app>/AppOptics`
`CORECLR_ENABLE_PROFILING`	1
`CORECLR_PROFILER`	{`824293AD-22E2-4DAA-BC28-166C140543BE}`
`CORECLR_PROFILER_PATH`	`<published-dotnet-core-app>/AppOptics/AppOpticsProfiler.so`

Any application that starts with the dotnet command (runs under the dotnet process) is automatically considered for instrumentation. See Instrumenting non-dotnet processes.

Adding the AppOptics.Agent ASP.NET Middleware

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

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

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

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

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

Troubleshooting

After installing the agent if traces and metric data do not appear in the AppOptics dashboard, see Troubleshooting (legacy agent) for resolution tips.

Log File Locations

The AppOptics.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/appoptics/DotNetAgentLog*
Windows: C:\Windows\TEMP\AppOptics\DotNetAgentLog*