AppOptics.Agent NuGet package (legacy agent)

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

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.

1. Add the AppOptics.Agent NuGet package to your .NET Core/5+ project.

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

3. 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.
4. 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

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*