• Print
  • Share
  • Dark
    Light

Advanced Installation Topics

  • Updated on 01 Nov 2018
  • 5 minutes to read
  • Contributors

In some circumstances, you may find you need to install the APM Profiler for .NET in a manner other than the default installation approach. This documentation covers those outside-the-norm installation methods that are available to you. You will also find some additional details here about how the .NET Profiler works.

Technical and Performance Notes

Performance

The Retrace .NET Profiler has been specifically designed to minimize overhead incurred by profiling and to be used in an “always on” manner, even on production web servers.  

However, web servers already under high load and suffering CPU and Memory contention should not have any CLR profiling (Retrace or other) run for a significant period of time, for risk of creating further performance issues. In this event, if profiling is necessary for debugging an application, Stackify recommends enabling profiling for only short durations to capture / reproduce the event that you are trying to profile.

Once you enable the APM profiler and restart IIS, you will observe a slightly longer startup time to your application (5-10 seconds) as the CLR passes startup events to the profiler.

Per User Account Registration

It is important to note that CLR profilers are registered per user account and not per process or even globally. For example, if a profiler is registered for the account NETWORK SERVICE, all .NET processes running under that account will be profiled. During installation, the Retrace .NET Profiler will be registered with all accounts that are running IIS Application Pools, and as such attempts to minimize profile collection to just IIS ASP.NET applications. The data collector will only display profiler output in the Retrace Dashboard for ASP.NET applications.

x86 and x64 Processes

The Retrace .NET Profiler will work with both x86 and x64 processes.

IIS "Classic" Application Pools

If you are running IIS with an application pool set to classic mode, please review this document: Install Stackify Module For Classic IIS App Pools

Command Line Installation

Performing a Silent Install

To perform a silent install of the Stackify agent, run the following in the Command Prompt in the directory that you installed the agent:

"Stackify Version#.exe" /s /v"ACTIVATIONKEY=activationkey ENVIRONMENT=\"environment\" /qn /l*v .Log.txt"

You will need to specify the installer version number, ACTIVATIONKEY and ENVIRONMENT parameters with your information.

Note: The " escapes are only necessary if the environment name has a space or special characters in it. The /l is optional. This will create a log file of the installation called Log.txt.

Uninstalling Silently

You can perform a silent "uninstall" in a similar way as the installation script above, this time with an argument of /x (the standard MSI argument) to uninstall:

"Stackify v[Version#].exe" /x

Note: If the agent is still on the same version used from original install, just execute that same package again from wherever you saved it.

Note: If the agent has been auto-updated, you will want to execute this from the file found in "Program Files (x86)\Stackify\AgentExeStaging".

Silent Install with APM Profiler Disabled

If you want to silently install without enabling the CLR profiler for Retrace add the ENABLEPROFILER parameter and set it to 0. It would look like this in the Command Line:

"Stackify Version#.exe" /s /v"ACTIVATIONKEY=activationkey ENVIRONMENT=\"environment\" ENABLEPROFILER=0 ENABLEREMOTE=True /qn /l*v .\Log.txt"

Note: If you disable APM during the installation, this setting will still be honored after updates of the agent.

If you are using a configuration management tool such as Puppet or Chef, you will not want to automate the install of a specific version. Instead you can use the Powershell script below to download the most recent version and then install it.

$storagedir = $pwd
$webclient = New-Object System.Net.WebClient
$url = "https://s1.stackify.com/account/agentdownload/index"
$file = "$storagedir\StackifyInstall.exe"
$webclient.DownloadFile($url,$file)
& $file /s /v"ACTIVATIONKEY=your_Activation_key ENVIRONMENT=`"Put your environment here`" ENABLEPROFILER=0 /qn /l*v .Log.txt"

Save this as a .ps1 file and you can execute it by running it manually in the directory where the .ps1 file is located:

.\filename.ps1

Or you can have a runbook execute it.

Additonal Command Line Options

Setting Environment Name

`ENVIRONMENT=\"Your environment name\"`
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" /qn /l*v .\Log.txt"

Note: If you are reinstalling the agent on a device that was previously setup, you will need to change the environment name in the environment dropdown box of the server settings.

Install with the CLR Profiler Enabled

ENABLEPROFILER=1
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" ENABLEPROFILER=1 RESTARTIIS=1 /qn /l*v .\Log.txt"

Note: This install will not automatically restart IIS. You will need to restart IIS manually before APM data will be collected.

Enabling Automatic an IIS Restart

Retrace and Stackify's .NET profiler will not be able to collect data until IIS has been restarted. We recommend having the installer automatically restart IIS.

RESTARTIIS=1
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" ENABLEPROFILER=1 RESTARTIIS=1 /qn /l*v .\Log.txt"

 

Enabling Profiling of .NET Core and Windows Services

ATTACHALL=1
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" ENABLEPROFILER=1 RESTARTIIS=0 ATTACHALL=1 /qn /l*v .\Log.txt"

Note: There are some additional steps needed to configure Retrace for non-IIS apps.

Enabling IP Masking

Enabling the IPMASK argument will remove the device's IP address from showing up in the Server Dashboard and Server Settings. It will also mask the IP address in our internal databases.

IPMASK=1
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" IPMASK=1 /qn /l*v .\Log.txt"

Note: If this device was previously set up with an agent, you will want to first remove the device from the portal.

Enabling a Device Alias

Setting the device alias will change the default ComputerName variable that the agent uses to determine the host name. This can also be set in the Server Settings modal.

DEVICEALIAS="Your device alias name"
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=YOUR_KEY ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" DEVICEALIAS=\"ENTER_ALIAS_HERE\" /qn /l*v .\Log.txt"

Modifying the Stackify.ini

If you wish to modify the settings on a server that is already running a Retrace agent, but don't want to control it via the Retrace Dashboard

Enable/Disable APM Profiler

  1. Open [Install Drive]:Program Files (x86)/Stackify/Stackify.ini. Find the following [Features] section:
[Feature]
EnableProfiler=1
EnableRemoteAccess=1
RestartIIS=1
ProfilerStarted=0
  1. Modify the following keys to alter the profiler settings:
EnableProfiler=1
  • Blank = disabled
  • 0 = disabled
  • 1 = enabled
RestartIIS=1

(IIS behavior when the the "EnableProfiler" setting has changed and the agent restarts)

  • Blank = no restart
  • 0 = no restart
  • 1 = restart
  1. Restart the service Stackify Monitoring Service by the Windows Services console

Note: Depending on the chosen method for enabling profiling, you may need to manually restart IIS for profiling and data collection to begin.