Retrace can be installed with Azure Cloud Services. This includes web and worker roles. To install Retrace, you need to setup a small startup task that automatically installs our agent.
Using the startup scripts ensures that whenever you redeploy your app or scale up that each server is properly monitored. More information about Azure Cloud Service Startup Tasks can be found via Microsoft's documentation.
We have put together the scripts that you will need to automate the startup tasks. You can find these scripts below and on Github. A complete zip file can be downloaded on the Github page.
This script is supplied by Microsoft and wraps all command-line execution so it is logged to disk. This is essential when troubleshooting issues with the agent installation.
This script is the entry point of the startup task. It is used to setup the environment and then call the powershell script.
This script performs the actual download and installation of the agent. This script has evolved over time to include things like retry logic and usage of HttpClient, but it's overall purpose has not changed. It will download the installer from Stackify and execute it with the supplied parameters.
Prepare the Project
Include the logwrap.cmd, InstallAgent.cmd, and InstallAgent.ps1 files in the solution of the website or worker process that is being deployed. This should be at the root of the project. Be sure to set build action in Visual Studio to Copy Always on these files.
Setup ServiceDefinition.csdef & ServiceConfiguration.?.csconfig
Include this startup task in the ServiceDefinition.csdef of the Azure project in the solution.
... <ConfigurationSettings> <Setting name="Stackify.ApiKey" /> <Setting name="Stackify.Environment" /> </ConfigurationSettings> ... <LocalResources> <LocalStorage name="StackifyTemp" sizeInMB="1024" cleanOnRoleRecycle="false" /> </LocalResources> <Startup> <Task commandLine="logwrap.cmd InstallAgent.cmd" executionContext="elevated" taskType="simple"> <Environment> <Variable name="ACTIVATIONKEY"> <RoleInstanceValue xpath="/RoleEnvironment/CurrentInstance/ConfigurationSettings/ConfigurationSetting[@name='Stackify.ApiKey']/@value" /> </Variable> <Variable name="ENVIRONMENT"> <RoleInstanceValue xpath="/RoleEnvironment/CurrentInstance/ConfigurationSettings/ConfigurationSetting[@name='Stackify.Environment']/@value" /> </Variable> <Variable name="STACKIFYTEMP"> <RoleInstanceValue xpath="/RoleEnvironment/CurrentInstance/LocalResources/LocalResource[@name='StackifyTemp']/@path" /> </Variable> </Environment> </Task> </Startup> ...
... <ConfigurationSettings> <Setting name="Stackify.ApiKey" value="[Your API/Activation Key Here]" /> <Setting name="Stackify.Environment" value="[Your Environment Here]" /> </ConfigurationSettings> ...
Of course, replace [your Stackify Activation Key] with your real activation key (which you will find on first login, or under your Settings -> Client Info page), and [Environment name] with an environment name that reflects the environment that your application and roles will be running within. Environment name can be anything you choose, and the only real key here is to be sure you're consistent with your use of Environment (i.e. don't deploy Staging resources with Environment set to Production).
Using with Worker Roles
Special logic exists so that if you enable our Retrace APM, it will automatically profile your main Worker Role process without having to create the ProfilerProcess.txt file specifying it. It also restarts your app after it enables the profiler.
ATTACHALL=1 in the InstallAgent.ps1 script.
How to Install with APM Disabled
By default, for Web Roles, the InstallAgent.ps1 file will be configured to enable APM by default.
ENABLEPROFILER=0 in the InstallAgent.ps1 script.
Advanced: Selective Environment Deployment Instructions
If you want to make sure that you don't install the agent on certain roles (roles used for Dev or QA for example), you can do something like the following to perform a selective deployment.
1. Add a config setting to ServiceDefinition.csdef called "DeployStackify", ie.
<ConfigurationSettings> <Setting name="DeployStackify" /> </ConfigurationSettings>
2. Also add another variable to the startup task that reads from this setting, ie.
<Variable name="DEPLOY"> <RoleInstanceValue xpath="/RoleEnvironment/CurrentInstance/ConfigurationSettings/ConfigurationSetting [@name='DeployStackify']/@value" /> </Variable>
3. In each transform of the service config, provide the value for this setting, ie.
<ConfigurationSettings> <Setting name="DeployStackify" value="true"/> </ConfigurationSettings>
4. In the InstallAgent.cmd file, read this variable and decide whether or not to install, ie.
if "%DEPLOY%"=="false" goto :EOF