• Print
  • Share
  • Dark
    Light

Cloud Services

  • Updated on 05 Sep 2018
  • 3 minutes to read
  • Contributors

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.

logwrap.cmd

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.cmd

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.

InstallAgent.ps1

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.

NodeJS
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.

ServiceDefinition.csdef

...

    <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