Migrate the .NET Library from AppOptics to SolarWinds Observability

AppOptics users can use the following information to migrate to SolarWinds Observability.

Before you start

Verify the following to ensure the library can collect and transmit data:

• The platform where your APM library will be installed is supported.

• Your application components are supported by the library.

• Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

  If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Migrate from AppOptics on Windows

1. Stop the applications that are being instrumented, such as Windows services and IIS.

   • To stop IIS, run the following command:

     iisreset /stop

   • To stop a Windows service, run the following command. Replace ServiceName with the actual service name.

     sc stop ServiceName

   Ensure that IIS is completely stopped before performing any installation or uninstallation tasks.

2. Uninstall the AppOptics .NET Agent.

3. Purge the AppOptics .NET Agent.

4. Download the installer and install the SolarWindsAPM .NET Library.

5. Set the collector configuration option to the AppOptics endpoint collector.appoptics.com:443. Use a config option or an environment variable to override the default APM collector endpoint.

6. If you have custom configurations in the AppOptics .NET Library configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. You can copy configuration sections, such as application elements.

   The API token portion of the serviceKey attribute must be updated to be a valid SolarWinds Observability token.

   The configuration files can be found in the following locations:

   • AppOptics: %PROGRAMFILES%/AppOptics/APM/dotnet/agent.config

   • SolarWinds Observability: %PROGRAMFILES%/SolarWinds/APM/dotnet/solarwinds_apm.config

   For more information on configuration settings, see Configure the .NET Library.

7. Start the applications to be instrumented, such as Windows services and IIS.

   To start IIS, run the command iisreset /start.

Installation file and installation location

AppOptics .NET Agent

• Installer file name: DotNetAgent_Setup.exe
• Installation location: %PROGRAMFILES%/AppOptics/APM/dotnet

SolarWinds Observability .NET Library

• Installer file name: SolarWindsAPM_DotNetAgent_Setup.exe
• Installation location: %PROGRAMFILES%/SolarWinds/APM/dotnet

Log file locations

If you encounter issues during the migration, log files can be found in the following locations:

• AppOptics: %TEMP%/AppOptics (usually C:/Windows/Temp/AppOptics)

• SolarWinds Observability: %TEMP%/SolarWinds (usually C:/Windows/Temp/SolarWinds)

Migrate from AppOptics on Linux

1. Stop the applications that are being instrumented.

2. Remove the AppOptics .NET Agent files.

   The default location is ${HOME}/appoptics, but the files can be installed elsewhere.

3. Download the installer from https://agent-binaries.cloud.solarwinds.com/apm/dotnet/latest/solarwinds-apm-dotnet-agent-package.tgz. Then install the SolarWindsAPM .NET Agent.

4. Set the collector configuration option to the AppOptics endpoint collector.appoptics.com:443. Use a config option or an environment variable to override the default APM collector endpoint.

5. Update the environment variables. See SolarWinds Observability environment variables below.

6. If you have custom configurations in the AppOptics .NET Agent configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. You can copy configuration sections, such as application elements.

   The API token portion of the serviceKey attribute must be updated to be a valid SolarWinds Observability token.

   The configuration files can be found in the following locations:

   • AppOptics: agent.config

   • SolarWinds Observability: solarwinds_apm.config

   For more information on configuration settings, see Configure the .NET Library.

7. Start the applications.

Installation packages

• AppOptics .NET Agent: dotnet-agent-package.tgz

• SolarWinds Observability .NET Agent: solarwinds-apm-dotnet-agent-package.tgz

Environment variables

AppOptics environment variables

Environment variable	Value
APPOPTICS_HOME_APM_DOTNET	User-defined. Typically ${HOME}/appoptics
CORECLR_PROFILER	{824293AD-22E2-4DAA-BC28-166C140543BE}
CORECLR_PROFILER_PATH	${APPOPTICS_HOME_APM_DOTNET}/AppOpticsProfiler.so

SolarWinds Observability .NET Library environment variables

Environment variable	Value
SW_APM_HOME_DOTNET	User-defined. Typically ${HOME}/solarwinds
CORECLR_PROFILER	{AAAA7777-11FE-4F94-8EDA-312C0EDF4141}
CORECLR_PROFILER_PATH	${SW_APM_HOME_DOTNET}/solarwinds_apm_profiler.so

Log file locations

If you encounter issues during the migration, log files can be found in the following locations:

• AppOptics: /var/tmp/appoptics

• SolarWinds Observability: /var/tmp/solarwinds

Migrate the .NET Agent SDK

The SolarWinds Observability .NET Agent has been updated to use the W3C Trace Context Headers for distributed trace propagation. This update has required a few changes to the .NET Agent SDK and impacts how to receive and how to propagate trace context to external spans.

Trace propagation updates

• AppOptics: used the X-Trace header to pass context to distributed services.

• SolarWinds Observability: X-Trace header has been replaced with two new headers:

  • See Traceparent.
  • See Tracestate.

SolarWinds Observability SDK - See Tracing across external spans for updated instructions on how to propagate context to external spans.

Updated SDK methods

• Trace.StartTrace(). Optional parameters transparent and tracestate have been added. If your application receives requests from a higher span, such as an instrumented web server, you’ll receive a trace context for that trace. The trace context consists of two identifiers. One is the traceparent and the other is tracestate. Both must be provided to Trace.StartTrace() if a trace needs to be continued. See Tracing across external spans. If traceparent and tracestate are not provided and there currently isn’t a trace already in progress, a new trace will be started.

• Trace.ContinueTrace() method has been removed. Trace.StartTrace() with the traceparent and tracestate parameters set should be used instead.

• EndTraceAndReturnTraceId() was updated to ReportAndReturnTraceContext(). The updated method now returns the TraceContext as an object. The tracecontext now requires the two fields traceparent and tracestate.

• Trace.GetCurrentTraceId() has been removed from the SDK. TraceContext.GetCurrent() should be used instead.

• GetCurrentLogTraceId. The output format of the GetCurrentLogTraceId SDK function has been updated.

  • AppOptics format: <trace-id>-<sample-flag>

  • SolarWinds Observability format: TraceId=<trace-id> SpanId=<span-id> TraceFlags=<sampled-flags>

SDK methods removed

• Trace.ContinueTrace()

  • Trace.StartTrace() with the traceparent and tracestate parameters set should be used instead of Trace.ContinueTrace().

Troubleshooting

After upgrading to the SolarWinds Observability .NET Library, you are getting an unhandled exception when trying to run a web application

The AppOptics .NET Agent might have had an error when it was uninstalled. If that is the case, the unhandled exception message would contain the following text:

Profiler CLSID: '{824293AD-22E2-4DAA-BC28-166C140543BE}'

To resolve this issue:

1. Stop IIS.

   To stop IIS, run the command iisreset /stop.

2. Uninstall the SolarWinds Observability .NET Library.

3. Restart the workstation.

4. Open RegEdit, and remove the following entries:

   • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\W3SVC\Environment

   • HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\WAS\Environment

5. Purge the AppOptics .NET Agent.

6. Install the SolarWinds Observability .NET Library.

7. Restart workstation.

8. Start IIS.

   To start IIS, run the command iisreset /start.