Documentation forSolarWinds Observability

Migrate the .NET Library from AppOptics to SolarWinds Observability

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

Migrate from AppOptics on Windows

  1. Stop the applications that are being instrumented (for example, Windows services and IIS).

    To stop IIS, run the command iisreset /stop.

  2. Uninstall the AppOptics .NET Agent.

  3. Download the installer, and install the SolarWindsAPM .NET Library.

  4. If you have custom configurations in the AppOptics .NET Library configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. For example, 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.

  5. Start the applications to be instrumented (for example, 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 from 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. Update the environment variables. See SolarWinds Observability environment variables below.

  5. If you have custom configurations in the AppOptics .NET Agent configuration file, you can copy them to the SolarWindsAPM .NET Agent configuration file. For example, 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.

  6. 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:

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().