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
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.
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)StackifyAgentExeStaging”.
Silent Install with APM+ Disabled
If you want to silently install without enabling the CLR profiler for APM+ 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:
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
"Stackify_v[Version#]" /s /v"ACTIVATIONKEY=[YOUR KEY] ENVIRONMENT=\"ENTER_ENVIRONMENT_HERE\" ENABLEPROFILER=1 RESTARTIIS=0 /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
"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
"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.
"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
1) Open [Install Drive]:Program Files (x86)/Stackify/Stackify.ini.
Find the following [Features] section:
[Feature] EnableProfiler=1 EnableRemoteAccess=1 RestartIIS=1 ProfilerStarted=0
2) Modify the following keys to alter the profiler settings:
- Blank = disabled
- 0 = disabled
- 1 = enabled
(IIS behavior when the the “EnableProfiler” setting has changed and the agent restarts)
- Blank = no restart
- 0 = no restart
- 1 = restart
3) 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.