Cloud Services
- 3 Minutes to read
- Print
- DarkLight
- PDF
Cloud Services
- 3 Minutes to read
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
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.
Installations Scripts
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.
logwrap.cmd
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.
InstallAgent.cmd
This script is the entry point of the startup task. It is used to setup the environment and then call the powershell script.
InstallAgent.ps1
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.
Node.js
If you are running Node.js in an Azure role, you will need the Install.cmd and Install.ps1 files to be in the bin directory of your web role, not in the root.
Setup ServiceDefinition.csdef & ServiceConfiguration.?.csconfig
Include this startup task in the ServiceDefinition.csdef of the Azure project in the solution.
StackifyTemp
StackifyTemp is used to overcome a restriction of Azure Cloud Services, specifically the limitation of the default TEMP directory to 100mb. We do require a minimum .NET Framework version, as well as other prerequisites, that do require usage of the TEMP directory. If StackifyTemp is not provided, then it is possible that the installation will fail silently due to a failed prerequisite. More information can be found via Microsoft's documentation.
...
<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>
...
ServiceConfiguration.?.csconfig
...
<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.
Worker Role Profiling
To install the agent, follow the directions in this article and be sure to set
ENABLEPROFILER=1 and 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.
Disable All Profiling
If you do not want to have APM enabled, set
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
Was this article helpful?