Getting to Know the Team System Management Model Designer

patterns & practices Developer Center
Alex Homer, Microsoft Corporation
August 2008

This article introduces the Team System Management Model Designer Power Tool (more commonly referred to as the TSMMD). This powerful and extremely useful addition to Visual Studio 2008 can help application architects and developers to build applications that are more manageable and that have a lower total cost of ownership (TCO).

Contents

Introduction
Manageable Applications - Designed for Operations
What Is the TSMMD?
Aspects, State Transitions, and Health
Monitoring and Managing Applications
Creating a Management Model
Generating the Instrumentation Helpers
Using the Instrumentation Helpers
Generating a Management Pack for System Center Operations Manager
Conclusion

Introduction

Modern automobiles have become so complex that they require more computing power than that of the average desktop computer from of a few years ago. It's no longer enough for the car's operating system to just fire the spark plugs a few thousand times a minute. Now, especially on top-of-the-range models, it has to manage traction control, automatic braking systems, cornering control, fuel feed pressure, and more. Then, of course, there's the gadgetry built into many new cars: automatic windshield wipers and lights, satellite navigation, entertainment systems, parking sensors, climate control; the list goes on and on.

So what happens when it goes wrong? Usually, an engine-shaped red light is all the "user" sees. This basically means: "drive to your nearest dealer and let them fix whatever has failed." The dealer plugs the car into another computer, which prints out reams of data about the system events, performance, and status. They immediately know that they just need to fit a replacement knurdle widget and it will all work fine again.

So, do your applications behave like this? When they go seriously wrong, does the user just see an error message saying "Sorry, something failed, please contact your system administrator"? That's fine, but what does the system administrator do next? Do you provide them with the facility to extract useful information that will help them to locate the fault and fix it? Or do they have to run the application themselves and try to figure it out from experience? Or maybe they simply phone the development team and say "It's broken again..."?

Manageable Applications - Designed for Operations

Architects and developers have a lot to think about when they start to design and build an application—the structure, the componentization, the technologies to use, interaction with services and users, algorithms, accessibility, and more. However, it's not unusual to overlook important issues about how the system administrator will deploy and manage the application afterward. There is often a surprisingly wide disconnect between the developer and the system administrator. Developers may not be aware of exactly how their application will be deployed and how the operators will monitor performance and maintain the application to ensure it meets the service level agreements (SLAs) or business requirements.

Yet development is generally only 20 percent to 25 percent of the total cost of ownership (TCO) of an application. The bulk of the lifetime cost is taken up in deployment, setup, configuration, monitoring, maintenance, and updates. So it makes obvious sense to try and minimize these costs, even if it does result in marginal increases in development time, cost, and application complexity.

The good news is that, using tools such as the Team System Management Model Designer (TSMMD), you can build applications that are far more manageable and administrator-friendly without incurring significant extra cost. In fact, the TSMMD can actually reduce the work that developers have to do to implement better manageability in all kinds of enterprise-level applications.

This fits in well with several industry initiatives that aim to reduce the TCO of complex and service oriented applications by providing guidance and tools that maximize manageability. Microsoft is working on a wide-ranging initiative named Dynamic IT, together with a guidance project named Design for Operations.

Note

For more details about the Dynamic IT initiative, see Dynamic Systems Initiative on the Microsoft Business & Industry Web site. For more information about the Design for Operations project, see the community page on the CodePlex Web site.

What Is the TSMMD?

Developers and administrators have integrated tools in Visual Studio Team System that help them to design applications. These tools include the Application Design, System Design, and Logical Datacenter Design templates available in the Distributed Systems group of the Visual Studio New Project dialog box. However, these tools do little to help architects and developers think about manageability during the design phase. They concentrate on the structural design, the deployment platform, and the connectivity of each component of the application.

The TSMMD is also a model designer, but it concentrates on how architects and developers will build a management model. This type of model describes the health of an application, the status of each component, the performance indicators it will expose, and the events that it will raise to provide a history about the issues occurring within the application at run time. Figure 1 shows a very simple management model for an application that contains a customer application component and a database containing customer information.

Figure 1
A simple management model showing the health definitions and the instrumentation that supports them

It is immediately obvious that applications built to implement the features of a manageability model will provide the same type of experience as that experienced by the car dealer. System administrators will have access to data about the system events, performance, and status. In addition, the model can provide extended information about each change of state and each event that can help administrators and operators to debug issues, quickly resolve them, and confirm that the application is once again operating correctly.

Aspects, State Transitions, and Health

The TSMMD manageability model is based on the division of an application into individual entities whose health state indicates and affects the overall health and status of the application. Each entity exposes aspects that correspond to factors that can change the health state. For example, a DatabaseConnectivity aspect will indicate the status of a connection to a database. Changes in the connectivity ("state transitions") will cause a change to the status of that aspect.

Aspects may be critical or non-critical, and the health state that they expose can vary depending on the effect of the corresponding state transition on the overall application. For example, if some entity has a working connection to a database, its DatabaseConnectivity aspect will be GREEN (healthy). If it loses connectivity to the database and this causes the application to fail, the aspect will be RED (failed). However, if the application can operate without the database, perhaps because it caches the data or can failover to another database, the aspect will be YELLOW (impaired, or operating at less than full operational state).

Aspects can also expose continual performance information. For example, a TransactionTime aspect may be configured so that it is GREEN when the average transaction time is less than 3 seconds, YELLOW if it is between 3 and 10 seconds, and RED if it is more than 10 seconds. By defining a comprehensive set of aspects for each entity in the application, and implementing the events and performance counters to drive these aspects, architects and developers can make it much easier for administrators and operators to monitor, debug, and resolve problems with that application.

Monitoring and Managing Applications

There are several comprehensive tools and environments available for administrators and operators to use to monitor and manage applications. Microsoft System Center Operations Manager provides a wide range of features that allow administrators and operators to maintain a large number of applications, servers, and client systems. By implementing a management model that integrates with such tools, architects and developers make it easy for administrators and operators to monitor the status of an application, see continuous performance information, detect problems with the application, and resolve these problems.

In addition to simply exposing aspects, architects and developers can include "knowledge" in the model that is available within the monitoring environment. An aspect that indicates performance of a specific entity could include knowledge that lists the main factors that will affect performance and how to optimize the resources the entity requires. For example, if the operator sees a change to the warning (YELLOW) state for transaction time, he or she can view knowledge that will indicate which database drives this entity. The operator can then check the status of that database connection and see knowledge stored in that aspect that will help the operator to resolve the issue—perhaps by switching to a different database.

You can see from this how manageable applications not only make it easier for administrators and operators to fix problems, but they can also provide early warning that there are issues that may cause a failure. For example, the record of performance and aspect states can act as justification for replacing failing components, expanding the hardware, or providing extra connectivity. In addition, it can also make it easier to show that an application is performing as required by meeting SLAs and business requirements.

Creating a Management Model

After you install the TSMMD, you can build a new management model simply by creating a new TSMMD Project solution in Visual Studio 2008, enabling the TSMMD Guidance Packages, and then populating the model. The TSMMD contains a series of wizards that help to guide you through each stage and propose sensible default values. The following sections provide a brief overview of the process:

• Create a TSMMD Management Model Solution
• Add a Managed Entity to the Model
• Add an Aspect to a Managed Entity
• Specify the Instrumentation Implementations for an Aspect
• Validate the Model

You can follow a detailed step-by-step walkthrough for building a simple management model to see the process in more detail. The walkthrough is included in the "Getting Started" section of the documentation that is automatically installed with the TSMMD.

Note

The TSMMD uses the patterns & practices Guidance Automation Extensions (GAX) to manipulate the model designer and implement the wizards. You can obtain the GAX from the Microsoft download site. When you create a new solution, you must open the Guidance Package Manager from the Tools menu in Visual Studio 2008 and enable the two guidance packages named Team System MMD Instrumentation and Team System MMD Management Pack Generation.

Create a TSMMD Management Model Solution

To create a new management model, you simply start Visual Studio 2008, point to New on the File menu, click Project, and then click TSMMD Project in the list of projects. On the Visual Studio Tools menu, click Guidance Package Manager, click the Enable/Disable Packages button, select the two guidance packages named Team System MMD Instrumentation and Team System MMD Management Pack Generation, and then close the Guidance Package Manager.

Now you can select the top-level management model entry named Operations in the Management Model Explorer window and set the Name, Description and Knowledgebase properties. Expand the Target Environments node, select the target environment named Default, and then change the value of the properties to indicate the types of instrumentation that you want to use.

You use a target environment to define the types of instrumentation that are applicable to each deployment target. For example, you may not be able to use Windows Management Instrumentation (WMI) events or performance counters in a low trust environment such as a Web server. However, you will usually be able to use the full range of instrumentation types in a Windows Forms application that runs in a relatively high trust environment. By using multiple target environments, you can specify the types of instrumentation that you will implement in the application for each deployment target.

For example, Figure 2 shows a model with two target environments named Extranet and LocalIntranet. For the low-trust Extranet environment, the application will use Enterprise Library logging, Event Log events, and performance counters. The high-trust LocalIntranet environment can use these or other instrumentation technologies such as Trace File or WMI events.

Figure 2
Specifying instrumentation types for a target environment

Add a Managed Entity to the Model

You can populate a management model by dragging managed entity items from the Visual Studio Toolbox onto the designer surface. However, a better approach is to right-click the top-level management model node in the Management Model Explorer pane and click New Managed Entity Wizard. In the wizard, you specify the name and type of the new entity. It can be an ASP.NET Web application, an ASP.NET or WCF Web service, a Windows executable application, or a Windows service. You also specify the discovery method for the entity. This defines how the monitoring system will locate the entity on each monitored computer; for example, the IIS virtual root alias for an ASP.NET entity or a Windows Registry entry for an executable application.

The wizard creates the new entity and adds it to the design surface and to the Management Model Explorer. You can select the entity and modify the properties afterwards if required. Figure 3 shows the default values in the Visual Studio Properties window for an ASP.NET managed entity. You can run the wizard multiple times to generate all the managed entities you require. However, you can only modify existing managed entities by using the Properties dialog box.

Figure 3
The properties for an ASP.NET managed entity

Note

The main differences between the entity types you can select are the extensions that the TSMMD will automatically implement in the management pack you generate from the model. For example, an ASP.NET managed entity can automatically generate a series of monitors for the response time, the ASP.NET exception count threshold, and the error performance threshold. You can configure these extended properties in the Management Model Explorer, as shown in Figure 3.

You can also use the Connection item in the Visual Studio Toolbox to create connections between entities, although connections are only used in the generated management pack to indicate that one component uses another component. They have no influence on the management model. However, you can use connections and the External Managed Entity type (for which you do not specify instrumentation) to indicate sections of the overall application that lie outside the boundaries of your model, and you can even use this approach to build multiple models for a large or complex application.

Add an Aspect to a Managed Entity

Each managed entity in your model can implement one or more aspects that indicate the health state of that entity. To add an aspect, you right-click a managed entity on the design surface or in the Management Model Explorer and then click New Aspect Wizard. The wizard prompts for the name and category of the aspect. The category is one of those found in most monitoring environments, such as Configuration, Availability, Performance, or Security. You can also specify knowledge for display in monitoring tools that will be useful to administrators, as shown in Figure 4.

Figure 4
Generating a new event-driven two-state aspect using the wizard

You must also specify the aspect type in this page of the wizard. An aspect can be event-driven or based on a performance counter that you implement. In addition, as you saw earlier, an aspect can have two or three states:

• GREEN-RED (two-state). Use this aspect to generate a critical status that indicates this particular characteristic (such as a database connection) of the entity has failed.
• GREEN-YELLOW (two-state). Use this aspect to generate a warning status that indicates this particular characteristic of the entity is working at a reduced efficiency level or capacity. To add this type of aspect using the wizard, you choose the three-state aspect and then delete the RED indicator.
• GREEN-YELLOW-RED (three-state). Use this aspect when you want to indicate the status of some characteristic of the entity that can have a warning as well as a critical status. A common use of three-state aspects is with performance counters that indicate the status compared to pre-specified values, though it can be driven by three different events.

The wizard allows you to select an existing event or performance counter from the model, or define a new event or performance counter, as shown in Figure 5. In this example, the aspect is two-state and event-driven, and so you must specify two events.

Figure 5
Specifying the events for an aspect of a managed entity

The important point to remember here is that you are not actually specifying any particular type of event or performance counter implementation. You are only specifying the abstract event or performance counter that will drive the state changes in the aspect. In other words, you are not specifying an Event Log event or a WMI event; you are simply indicating that the aspect will be driven by an event with the name you specify. The next section describes how you specify the configurable (concrete) implementations of the instrumentation for these abstract events and performance counters.

In addition to generating the abstract events, you can add custom parameters to each event to pass situation-specific values to the event. For example, you can add a parameter that your code will populate with the name of the database for the NoDatabaseConnection abstract event shown in Figure 1 (near the beginning of this article). You add parameters directly in the Management Model Explorer pane—there is no wizard for this task.

Specify the Instrumentation Implementations for an Aspect

In the previous section, you saw how you can specify an aspect for a managed entity and define the events or measures that drive the state changes for that aspect. However, it is important to appreciate that these events and measures are not the actual events and performance counters that your application will implement. They are abstract definitions of the events and measures required to indicate state changes. These abstract events and measures then map to concrete implementations of the events and performance counters.

The reason for this is that you may have more than one target environment defined in your model. Different target environments may support different types of instrumentation. For example, a Web application may need to be deployed in both a low trust environment that only supports Enterprise Library Logging and a higher trust environment where the preferred instrumentation type is Event Log events. This means that you must define one instrumentation implementation for every event or measure in every target environment in the model.

Figure 6 shows an example of how the health states for an aspect map to the abstract events that drive each health state and how each abstract event maps to a configurable implementation appropriate for each target environment. In this example, there is only one target environment, so there is only one implementation for each event. If you added another target environment that only supports Enterprise Library Logging events, you would also have to define an Enterprise Library Logging event for each of the two abstract events.

Figure 6
The mappings between aspects, abstract events, and configurable implementations of these events

The TSMMD provides a wizard that you can use to generate the configurable implementations of events and measures. To start the wizard, right-click the abstract event or measure in the Management Model Explorer pane, and then click New Event Implementation Wizard (if it is an abstract event) or New Measure Implementation Wizard (if it is an abstract measure).

The first page of the wizard, shown in Figure 7, allows you to specify if you want to select an existing discovered event or measure or create new events or measures. The TSMMD contains a wizard that you can execute to discover details of instrumentation in the assemblies of an existing application. For example, if the application already contains the code to raise an event when database connectivity is lost, you may decide to use this event for the red health state of the NoDataBaseConnection aspect.

Figure 7
The New Event Implementation Wizard

Note

Existing instrumentation discovered by the TSMMD resides in the separate Discovered instrumentation section of the management model. If there is no discovered instrumentation, the corresponding option of the wizard is unavailable, as shown in Figure 7. There are limitations when using existing events. You cannot map them to a target environment, and you cannot use multiple implementations for an abstract event. It is usually preferable to define new events and measures using the wizard so that you can correctly match them to each target environment, specify any custom parameters you require, and automatically generate the appropriate instrumentation helper classes.

If you specify that you want to create new implementations for an event or measure, the wizard displays a list of the implementations you must create (one for each instrumentation type defined in the target environments of the model). If two target environments specify the same type of instrumentation (for example, they both support Windows Eventing 6.0 events), you only need to specify one Windows Eventing 6.0 implementation for this abstract event.

The wizard then displays a page for each of the event or measure implementations required. For each event or measure implementation, you specify the properties you require for that implementation. For example, you must specify the name, event ID, log name, and severity for events; plus any additional event-specific information such as the channel, task, and operation for a Windows Eventing 6.0 event. For a measure implementation, the only option is a performance counter, and you must specify the counter name, category name, and object name for the counter.

When specifying the details of an event, you can also specify a message template. This is a string that contains placeholders (such as %1 and %2) that the instrumentation helper will replace with the value of each parameter you defined for the corresponding abstract event.

Validate the Model

As you populate your management model, you can verify that you have provided all the required information and that all of the items have valid property values, by validating the model. You can validate the complete model, individual entities, the set of aspects for an entity, or the instrumentation for an entity. Simply right-click the top-level entry in the Management Model Explorer or right-click the section you want to validate, and then click Validate or Validate All.

The TSMMD examines the model artifacts and reports any errors or warnings in the Visual Studio Error window. Warnings will usually be property values that you should provide information for, but it is not mandatory to provide information for them. However, you should aim to achieve a model with no warnings.

Generating the Instrumentation Helpers

After you build the management model, or at any point during this process (where the model is valid), you can generate the set of instrumentation helper classes. These classes contain the code that raises the appropriate event depending on the currently selected target environment. In addition, this process generates installer classes to help you install the instrumentation helpers and provides the core assemblies for the instrumentation and configuration that you must install on the target computer.

Figure 8 shows the contents of the Instrumentation folder that the TSMMD generates for a simple model that contains an entity named CustomerApplication that uses only Event Log events. The following are projects that the TSMMD generates inside the Instrumentation folder:

• An API project for each entity in the model. This contains an abstract class with methods that allow the application to discover if it can raise the event or increment the counter and methods to raise the event or increment the counter. A concrete class in the related implementation project overrides these methods.
• An implementation project for each entity and target environment in the model. The implementation of these methods depends on the type of event or measure defined in the model for the associated target environment. As an example, a model may contain a managed entity that has one abstract event, WMI event and Event Log event implementations of the abstract event, and two target environments named LocalIntranet and MedTrust. In this case, the code generation process will create two implementation projects. Each project contains a concrete class that implements the methods in the related abstract class for each of the events.
• A technology project for each instrumentation technology referenced in the model. This contains the installer classes and associated resources you use to install the instrumentation on the target computer.

Figure 8
The contents of the generated instrumentation folder for a simple model with one managed entity

In addition, the instrumentation generation process creates a configuration file named InstrumentationConfiguration.config that contains the configuration settings you must include in your application configuration file (Web.config or App.config). You can see this file at the end of the Instrumentation folder contents in Figure 8. The settings in this file determine the way the generated instrumentation will behave at run time.

Using the Instrumentation Helpers

In the previous section, you saw how the TSMMD automatically generates the instrumentation helper classes required to implement in your application the instrumentation you define in your model. To use these helpers, you add a reference to the projects, or copy the assemblies they generate when you compile your project into the bin folder of your application, and then call the exposed methods when you want to raise an event or increment a performance counter.

Raising Events

The generated instrumentation contains a method to raise every abstract event defined in the model. For example, if you have an abstract event named NoDatabaseConnection, the instrumentation API will contain a method named RaiseNoDatabaseConnection that you can call as shown here.

CustomerApplication.API.CustomerApplicationAPI.GetInstance().RaiseNoDatabaseConnection();

CustomerApplication.API.CustomerApplicationAPI.GetInstance().RaiseNoDatabaseConnection()

If you have defined any parameters for the abstract event, you specify the values you want to pass to the instrumentation when you call the method. The instrumentation helper will insert the values into the message template you specified when you defined the abstract event. For example, if the NoDatabaseConnection event accepts the name of a database as a parameter, you would call the method as shown here.

CustomerApplication.API.CustomerApplicationAPI.GetInstance().RaiseNoDatabaseConnection("SalesDatabase");

CustomerApplication.API.CustomerApplicationAPI.GetInstance().RaiseNoDatabaseConnection("SalesDatabase")

The generated instrumentation also contains a CanRaise method that you can call to see whether an event is supported in the currently selected target environment. At run time, you specify the target environment using the application configuration file (for more information, see the later section, "Configuring the Instrumentation").

Incrementing Measures

The generated instrumentation contains two methods to implement every abstract measure defined in the model. For example, if you have an abstract event named OrdersProcessed, the instrumentation API will contain methods named IncrementOrdersProcessed and IncrementByOrdersProcessed that you can call as shown here.

// Increment counter by the default value.
CustomerApplication.API.CustomerApplicationAPI.GetInstance().IncrementOrdersProcessed();

// Increment counter by a specified value.
CustomerApplication.API.CustomerApplicationAPI.GetInstance().IncrementByOrdersProcessed(5);

' Increment counter by the default value.
CustomerApplication.API.CustomerApplicationAPI.GetInstance().IncrementOrdersProcessed()

' Increment counter by a specified value.
CustomerApplication.API.CustomerApplicationAPI.GetInstance().IncrementByOrdersProcessed(5)

The generated instrumentation also contains a CanIncrement method that you can call to see whether a measure is supported in the currently selected target environment. At run time, you specify the target environment using the application configuration file (for more information, see the following section, "Configuring the Instrumentation").

Configuring the Instrumentation

After you write the application code that calls the instrumentation helper methods, you must configure the application. You copy the contents of the generated configuration file InstrumentationConfiguration.config into your application configuration file (Web.config or App.config), and then edit the values to specify the current target environment and the instrumentation granularity.

The <tsmmd.instrumentation> section of the configuration file contains an <add> element for every instrumented managed entity in the model. You set the targetEnvironment and the instrumentationLevel attribute values to specify the instrumentation behavior. For example, the following shows the instrumentation section of the configuration file for an application that has two managed entities. They will both use the instrumentation defined for a target environment named LocalIntranet.

...
<tsmmd.instrumentation>
  <add name="CustomerDatabase" targetEnvironment="LocalIntranet"
       instrumentationLevel="Coarse"/>
  <add name="CustomerWebService" targetEnvironment="LocalIntranet"
       instrumentationLevel="Coarse"/>
    ...
    ... all other managed entities in model listed here ...
    ...
</tsmmd.instrumentation>
...

This means that, if you subsequently deploy your application in a different environment, you only need to change the** instrumentationLevel** attribute values to specify the new target environment (as defined in the model). The application will then use the instrumentation appropriate for that target environment.

Instrumentation granularity defines when the helper classes will raise an event or increment a counter based on the Instrumentation Level property setting for each event and measure you defined in the model. You can set this property to Coarse, Fine, or Debug as you define each event and measure. Then, in the configuration file (shown in the preceding XML), you set the instrumentationLevel attribute for each managed entity to one of the values Coarse, Fine, Debug, or Off.

This capability to specify instrumentation granularity allows you to include in the model events and measures that you only want to use at specific times. For example, you may include instrumentation in your code that measures detailed performance of individual features of a managed entity ("Fine") or which is only useful when debugging a fault ("Debug"). You can then switch on and switch off this instrumentation by changing the granularity level for an entity.

Generating a Management Pack for System Center Operations Manager

Where administrators use tools or specialist environments to monitor and manage applications, you can make it easier for them to define all the monitors and rules required by providing them with your management model, which contains the health and instrumentation definitions. However, if your application will run in an environment where administrators use System Center Operations Manager to monitor and manage applications, you can make it even easier for them to manage your application by providing them with a pre-built management pack that they can install directly into System Center Operations Manager.

You can generate a management pack on demand using the menu option available in the Management Model Explorer window while you have a management model open in Visual Studio, or you can have the TSMMD automatically create the management pack as part of an MSBuild process or from the command line. You must set the properties in the Settings page of the project properties to specify whether the TSMMD will automatically generate a management pack when you generate instrumentation for the model and the parameters for the process that generates the management pack (see Figure 9). Administrators can then import this management pack directly into System Center Operations Manager.

Figure 9
The Settings page that controls management pack generation

Conclusion

As new tools and development environments appear, and the capabilities of the .NET Framework grow, it becomes easier to create complex and distributed applications made up of many services and components. However, monitoring the performance of these kinds of applications, and resolving run-time issues and failures, tends to become more complex. As the major costs incurred during the lifetime of an application occur after development is complete, it is increasingly important to adopt design and implementation techniques that minimize post-development costs.

Architects and designers can model the health states, state transitions, and the effects of state changes on the overall application to create an effective health model that will help administrators to monitor and manage the application. This model can also assist developers in creating the appropriate instrumentation to expose the health state and state transitions to monitoring systems, as well as providing administrators with valuable knowledge that will help them to deploy and manage the application. A management model is the combination of a comprehensive health model and instrumentation definition.

The Team System Management Model Designer (TSMMD) provides a familiar modeling environment within Visual Studio 2008 that allows architects and designers to create a management model, and it helps them to understand the way that the application will behave at run time. The TSMMD also helps developers to generate the appropriate instrumentation helper classes that they can easily consume in their application code, which reduces development time and effort, minimizes testing requirements, and helps to reduce errors. Finally, the TSMMD can generate management packs for System Center Operations Manager to save the administrator time and effort when deploying the application.