Real World: Creating Custom Performance Counters for Windows Azure Applications with PowerShell

Writing the proxy application as PowerShell script provides a few advantages over a console application. They are extremely lightweight since the PowerShell scripts do not need to be compiled and can be edited by most text editors. PowerShell scripts are executed by the PowerShell application (powershell.exe). If you are familiar with the C# programming language, then you will find that the PowerShell syntax is similar. You can reference any .NET class within a PowerShell script, such as the ones in the System.Diagnostics namespace. The System.Diagnostics namespace contains the performance counter classes that you will need to use to create your custom counters. The following example implements the logic to create several custom performance counters. The script is saved as New-PerfCounters.ps1.

$categoryName = "Our Custom Performance Counters"
 
$exists = [System.Diagnostics.PerformanceCounterCategory]::Exists($categoryName)
if ($exists)
{
[System.Diagnostics.PerformanceCounterCategory]::Delete($categoryName)
}
 
$counterData = new-object System.Diagnostics.CounterCreationDataCollection
 
$counter = new-object  System.Diagnostics.CounterCreationData
$counter.CounterType = [System.Diagnostics.PerformanceCounterType]::AverageCount64
$counter.CounterName = "Avg Bytes Uploaded"
$counterData.Add($counter)
 
$counter = new-object  System.Diagnostics.CounterCreationData
$counter.CounterType = [System.Diagnostics.PerformanceCounterType]::AverageBase
$counter.CounterName = "Avg Bytes Uploaded Base"
$counterData.Add($counter)
 
$counter = new-object  System.Diagnostics.CounterCreationData
$counter.CounterType = [System.Diagnostics.PerformanceCounterType]::AverageCount64
$counter.CounterName = "Avg KBytes Uploaded"
$counterData.Add($counter)
 
$counter = new-object  System.Diagnostics.CounterCreationData
$counter.CounterType = [System.Diagnostics.PerformanceCounterType]::AverageBase
$counter.CounterName = "Avg KBytes Uploaded Base"
$counterData.Add($counter)
 
[System.Diagnostics.PerformanceCounterCategory]::Create($categoryName, $categoryName, [System.Diagnostics.PerformanceCounterCategoryType]::SingleInstance, $counterData)

A task is defined by the command (executable), the task's permissions, and the task's type. A command can be anything that the operating system can run. Including a command in a task is analogous to executing commands from the command prompt. The permissions for the task can be either "elevated" or "limited." Elevated permissions execute the command under the NT AUTHORITY\SYSTEM account, which provides full administrative privileges. This includes permission to write to any location in the registry. Running as "limited" will start the command with the same privileges as the hosting process, which is the scenario we're trying to avoid.

To define startup tasks, add Task elements to the ServiceDefinition/WebRole/Startup section in the ServiceDefinition.csdef file. The following code shows how to define a task.

<ServiceDefinition ...>
  <WebRole name="MvcWebRole1">
    <Startup>
      <Task commandLine="StartupTasks\create-counters.cmd" executionContext="elevated" taskType="simple">
      </Task>
    </Startup>
</ServiceDefinition>

The commandLine attribute specifies a relative path to a batch file named create-counters.cmd, which executes the startup task. The path must be relative to the approot\bin directory for Web roles, or just the approot directory for Worker roles. The batch file is specified to be in a subdirectory named Startup Tasks. Therefore, the ASP.NET MVC project must have a folder with that name that contains the create-counters.cmd file. The following illustration shows the directory structure of the web application.

The taskType attribute defines the timing of execution of the Windows Azure role in relation to the startup task. The value of "simple" that is used in the example above indicates that the role is not started until the startup task completes. You can also specify a "background" and "foreground" values for the taskType attribute. A background task type means that the role will execute immediately after invoking the startup task, and does not wait for such task to complete. A foreground task type is similar to a background one with the exception that the role cannot be restarted until the startup task is completed. If you use a background task type, you can benefit with relatively faster deploy times since your role will start right away. However, using a background task type may introduce a race condition in your application with the creation of the performance counters and code using such counters. Instead, it is recommended that you use a simple task type so that the performance counters can be fully created prior to your code starting up. In addition, if your startup task contains errors, your role will fail with it, and cause your deployment to fail. This will provide immediate visibility into the error in the startup task.

An easy way to create the batch file is to use a text editor such as Notepad. After you save the file, you can include it in your project. If you create the batch file with Visual Studio, you must remove the default bytes that Visual Studio includes. (Windows Azure cannot process them.) These three bytes are 0xEF, 0xBB, and 0xBF. To delete the bytes, right-click on the batch file, select the Visual Studio Open With command, and then select Binary Editor. The following illustration shows how to choose the Binary Editor, and the bytes that you must remove from the file.

To include the batch file in the deployment, set the Copy to Output Directory build action either to the Copy if newer or Copy Always value. The following illustration shows how to set the build action.

After you have removed the extraneous bytes and set the build action, you can include the appropriate commands in the file. The content of the create-counters command file depends on whether the proxy application is a console application or a PowerShell script. A console application is started directly. A PowerShell script requires that the PowerShell.exe be invoked in order to run the script. The following sections explain both options.

Executing a Windows PowerShell script is simpler than executing a console application because there are no assembly references to manage. In fact, there is no project to reference at all. The only requirement is to save the script with the project, and ensure that it is published with the Copy to Output Directory value, just as the batch file is. The content of the create-counters.cmd file will execute the PowerShell application, and provide it with the appropriate parameters. The following code shows how to execute the PowerShell script.

powershell -ExecutionPolicy Unrestricted .\StartupTasks\new-perfcounters.ps1

Note
Even though the batch file is located within the StartupTasks directory, along with the new-perfcounters.ps1 file, it still executes relative to the approot\bin directory. For this reason, the path to new-perfcounters.ps1 must include the StartupTasks directory name.

The ExecutionPolicy Unrestricted switch and value indicates that the script can be run without any restrictions. This switch requires that the osFamily value in the ServiceConfiguration.cscfg file is set to 2.