Documentation forSolarWinds Observability SaaS

Migrate the .NET Library from AppOptics to SolarWinds Observability SaaS

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

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 SaaS, 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.

Remove other APM libraries from your .NET application before using the SolarWinds Observability SaaS .NET Library. See Do you have another profiler installed?.

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 by doing either of the following.

    The uninstallation executable is named uninsnnn.exe, where nnn is a number that starts at 000 and increments with each agent re-install.

    • Run the .NET agent uninstaller C:\Program Files\AppOptics\APM\dotnet\uninsnnn.exe.

    • Run the following command to uninstall the agent via the command line:

      # square brackets indicate optional parameters
# the pipe character separates multiple choices within an option
C:\Program Files\AppOptics\APM\dotnet\unins000.exe [/SILENT | /VERYSILENT] [/CLOSEAPPLICATIONS | /NOCLOSEAPPLICATIONS]

  3. Save a copy of the C:\Program Files\AppOptics\APM\dotnet\agent.config file so you can copy any custom configuration to the SolarWinds Observability SaaS APM Library config file, if needed.

  4. Purge the AppOptics .NET Agent.

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

  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 SaaS token.

    The configuration files can be found in the following locations:

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

    • SolarWinds Observability SaaS: %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 SaaS .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 SaaS: %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. Go to https://agent-binaries.cloud.solarwinds.com/?prefix=apm/dotnet/latest/ and download the appropriate version of the solarwinds-apm-dotnet-agent-package for your environment. Then install the SolarWindsAPM .NET Agent.

  4. Set the collector configuration option to the endpoint apm.collector.xx-yy.cloud.solarwinds.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 SaaS 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 SaaS token.

    The configuration files can be found in the following locations:

    • AppOptics: agent.config

    • SolarWinds Observability SaaS: solarwinds_apm.config

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

  7. Start the applications.

Installation packages

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 SaaS .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 SaaS: /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:

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.