Hands-On Lab

Introduction to PreEmptive Analytics

Lab version:11.0.60315.01 Update 2

Last updated:4/9/2013

Contents

Overview

Exercise 1: Installing PreEmptive Analytics Community Edition

Exercise 2: Instrumenting an Application

Exercise 3: Mapping the Application to Create Incidents in TFS

Exercise 4: Viewing Incidents in TFS

Overview

PreEmptive Analytics Community Edition for Team Foundation Server is a third party tool created by PreEmptive which allows you to gain insight into errors experienced by your customers. By instrumenting your application for analytics, you’ll be able to see these exceptions in Visual Studio Team Foundation Server 2012 so you can easily triage them right alongside your bugs. Exceptions are analyzed, correlated, and distilled into a set of “production incidents” based on the rules and operational thresholds you specify.

Figure 1

High-level overview of PreEmptive Analytics working with instrumented application

Prerequisites

In order to complete this lab you will need the Visual Studio 2012 virtual machine provided by Microsoft. For more information on acquiring and using this virtual machine, please see this blog post.

Exercises

This hands-on lab includes the following exercises:

  1. Installing PreEmptive Analytics Community Edition
  2. Instrumenting an Application
  3. Mapping the Application to Create Incidents in Visual Studio Team Foundation Server 2012
  4. Viewing Incidents in Visual Studio Team Foundation Server 2012

Estimated time to complete this lab: 60 minutes.

Exercise 1: Installing PreEmptive Analytics Community Edition

In this exercise, you will learn how to install PreEmptive Analytics Community Edition in a locally hosted scenario.

  1. Log in as Julia. All user passwords are P2ssw0rd.
  2. Open Team Foundation Server Administration Console from Start | All Programs | Microsoft Visual Studio Team Foundation Server 2012.
  3. Select the PreEmptive Analytics node under Additional Tools and Components.

Figure 2

PreEmptive Analytics setup page

  1. Select the Install PreEmptive Analytics Community Edition link.

Figure 3

Install PreEmptive Analytics Community Edition

  1. Click on Next to continue the setup wizard.

Figure 4

Location of Next button

  1. Read the license terms, select the check box for I accept the terms of this agreement, and then select the Next button.

Figure 5

License terms page

  1. On the Aggregator Service Configuration page, enter VSALM\Julia as the TFS Account Name, P2ssw0rd as the password, and then select Next.

Figure 6

Enter the account information

Note: The aggregator service must be hosted on a TFS server and have the permissions necessary to create and edit work items.

  1. Select Install to begin the installation for PreEmptive Analytics for TFS CE. This will take a few minutes to complete.

Figure 7

Location of the Install button

Note: When performing a basic installation like this, all components will be installed to the same machine. The PreEmptive Analytics Aggregator service will be installed and set to start automatically. A new database will be created in your local instance of SQL Server to store exception report data and a new website will be created in IIS to host the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages).

  1. Once the installation is finished, take a note of the endpoint shown in the dialog. This endpoint will be used later in the lab as the custom endpoint. Select Close to leave the setup program.

Figure 8

Location of the Close button

  1. The PreEmptive Analytics Aggregator Administration Console will be automatically launched after setup has completed.

Figure 9

PreEmptive Analytics Aggregator Administration Console

  1. Select the “+” button to add a connection to a Team Foundation Server.

Figure 10

Location of the “+” sign

  1. In the Connect to Team Project Collection dialog, select FabrikamFiberCollection in Team Project Connections and select the Connect button.

Figure 11

Connect to Team Project Collection

  1. Select the Apply button next to the FabrikamFiber project. This may take a few minutes to complete.

Figure 12

Location of the Apply button

Note: Provisioning TFS projects to work with PreEmptive Analytics involves importing the Incident work item type and some sample PreEmptive Analytics reports into the project template. In addition, the project is configured with settings that the PreEmptive Analytics Visual Studio extension needs in order to be able to configure exception sets and rules.

  1. PreEmptive Analytics is now setup with the FabrikamFiber project and is ready to accept exceptions from instrumented applications.

Figure 13

PreEmptive Analytics registered with team project

Exercise 2: Instrumenting an Application

In this exercise, you will learn how to instrument an existing application using PreEmptive Dotfuscator and Analytics.

  1. Launch Visual Studio 2012 from Start | All Programs | Microsoft Visual Studio 2012 | Visual Studio 2012.
  2. In Source Control Explorer, navigate to FabrikamFiber | Dev | FabrikamFiber.CallCenter and double-click on the FabrikamFiber.CallCenter.sln to open the FabrikamFiber solution.

Figure 14

Loading sample solution

  1. Now we will modify the source code and add an exception for the purpose of this lab. Go to Solution Explorer and open ServiceTicketsController.cs under FabrikamFiber.Web | Controllers.

Figure 15

Open ServiceTicketsController.cs file

  1. Scroll down to the Create method (line 92) and add the following line. Press Ctrl+S to save the file.

throw new Exception("Testing global error handler!");

Figure 16

Add an exception in Create method

  1. Select Build | Rebuild Solution from the main menu to initiate a clean rebuild.
  2. Now we need to instrument the web application so that exception information makes its way back to us. To do this, we will use the PreEmptive Dotfuscator and Analytics tool to configure the exception endpoint address and to identify the application source.
  3. Open Dotfuscator and Analytics Community Edition by selecting Tools | PreEmptive Dotfuscator and Analytics.
  4. The PreEmptive Dotfuscator and Analytics CE tool is launched.

Figure 17

PreEmptive Dotfuscator and Analytics CE

  1. Select the Inputs node followed by the Add Input button.

Figure 18

Add Input

  1. Navigate to C:\ws\Julia\ff\Dev\FabrikamFiber.CallCenter\FabrikamFiber.Web\bin, select FabrikamFiber.Web.dll, and finally select Open.

Figure 19

Select input

  1. Select the Analytics node under Configuration Options, and then select the Attributes tab.

Figure 20

Location of Analytics and Attributes buttons

  1. Right-click on the root node and select Add Attribute.

Figure 21

Location of Add Attribute option

  1. In the Add Attribute dialog, select PreEmptive.Attributes.ApplicationAttribute, then select OK. This attribute defines a GUID that ensures that data from this application stays separate from other applications that our company releases.

Figure 22

Add the ApplicationAttribute

  1. This is the place to enter the name, version and a unique identifier for the application. For the purpose of this lab, we will use a randomly generated GUID by clicking on the space next to Guid and then selecting the … button.

Figure 23

Generating an application GUID

Figure 24

Application GUID generated

Note: The GUID that you see will be different from what is shown in lab screenshots.

  1. Right-click on the root node and select Add Attribute to add the PreEmptive.Attributes.BusinessAttribute and select OK. This attribute distinguishes our company using a GUID provided by PreEmptive.

Figure 25

Add the BusinessAttribute

  1. Notice that the CompanyKey field has already been filled in.

Figure 26

The Business Attribute

  1. Next we need to specify the methods that denote where we want to begin and end data gathering by using SetupAttribute and TeardownAttribute.
  2. Expand FabrikamFiber.Web.dll | FabrikamFiber.Web.App_Start | NinjectMVC3, right-click on Start : void() and select Add Attribute.

Figure 27

Add Attribute to Start:void ()

  1. Select PreEmptive.Attributes.SetupAttribute, and select OK. This attribute will designate where we would like to begin data gathering as well as the exception endpoint to use.

Figure 28

Add the SetupAttribute

  1. Click on the space next to the CustomEndpoint property and enter the endpoint we were given during the setup of PreEmptive Analytics, VSALM:8000/message/Endpoint.ashx.

Note: If you clicked on the ellipses (…) button for the CustomEndpoint property, you would also see options for using PreEmptive’s hosted endpoints.

  1. Right-click on Stop:void()and select Add Attribute. This attribute simply designates the point where we want to stop collecting data.

Figure 29

Add attribute to Stop:void()

  1. Select PreEmptive.Attributes.TeardownAttribute, and select the OK button.

Figure 30

Add the TeardownAttribute

  1. At this point, our application is configured to send data to the configured endpoint. Now let’s see how we can specify that some exception data should be collected.
  2. Expand FabrikamFiber.Web.dll | FabrikamFiber.Web.Controllers | ServiceTicketsController, right-click on Create : System.Web.Mvc.ActionResult() and select Add Attribute.

Figure 31

Add Attribute to Create method

  1. Select the PreEmptive.Attributes.ExceptionTrackAttribute, and select the OK button. Since we are applying this to a specific method, only locally unhandled exceptions will be tracked.

Figure 32

Add the ExceptionTrackAttribute

  1. Select the Renaming node under Configuration Options, and then select the Options tab.

Figure 33

Setting renaming options

  1. Uncheck the Enable Renaming option.

Figure 34

Location of the ‘Enable renaming’ check box

  1. Save the configuration changes by selecting the Save button.

Figure 35

Location of the Save button

  1. Enter FabrikamFiber.Dotfuscator as the name of the project file, then select Save.

Figure 36

Enter file name and save

  1. Select the Build Project button in the PreEmptive Dotfuscator and Analytics CE window. This will modify the FabrikamFiber.Web.dll assembly with the specified instrumentation included. In the next exercise, we will create a subscription for the application so the generated exceptions will appear in TFS.

Figure 37

The location of the Build Project button

Exercise 3: Mapping the Application to Create Incidents in TFS

In this exercise, you will learn how to map the instrumented application to Team Foundation Server.

  1. Return to Visual Studio and navigate to Team Explorer to locate the PreEmptive Analytics hub. Team Explorer only shows the PreEmptive Analytics hub for team projects that have PreEmptive Analytics applied to them.

Note: In the event that you do not see the PreEmptive Analytics link, go ahead and try re-starting Visual Studio.

Figure 38

Team Explorer hub

  1. Select the PreEmptive Analytics link to load the PreEmptive Analytics view.

Figure 39

PreEmptive Analytics view

  1. Select the Configure link. This will load the PreEmptive Analytics Options window.

Figure 40

Location of the Configure button

  1. Add a subscription by selecting the ‘+’ button.

Figure 41

Location of the ‘+’ button

  1. Use Fabrikam Fiber as the name.

Figure 42

Enter the name

  1. Go back to the PreEmptive Dotfuscator and Analytics CE window. Copy the generated CompanyKey from the PreEmptive.Attributes.BusinessAttribute attribute (7d2b02e0-064d-49a0-bc1b-4be4381c62d3) and paste it in as the Company ID in the PreEmptive Analytics Options window.

Figure 43

Location of the CompanyKey in PreEmptive Dotfuscator and Analytics CE

Figure 44

Location of the Company ID in PreEmptive Analytics Options

  1. Go back to the PreEmptive Dotfuscator and Analytics CE. Copy the generated Application Guid from the PreEmptive.Attribute.ApplicationAttribute attribute and paste it in as the Application ID in the PreEmptive Analytics Options window.

Figure 45

Location of the Application GUID In PreEmptive Dotfuscator and Analytics CE

Figure 46

Location of the Application ID in PreEmptive Analytics Options

Note: You will see a different GUID for Application ID from the figures shown in the lab manual.

  1. For the purpose of this lab, set the rule Threshold to 1 so we can see the incident report after just one exception. Select the Close button.

Figure 47

Location of the Threshold and Close button

  1. Click Yes when asked to confirm saving.

Figure 48

Location of the Yes button

  1. The last step is to deploy the FabrikamFiber.Web.dll built by Dotfuscator to production. Use Windows Explorer and navigate to C:\ws\Julia\ff\Dev\FabrikamFiber.CallCenter\FabrikamFiber.Web\bin\Dotfuscated. Copy the FabrikamFiber.Web.dll from the Dotfuscated directory and paste it to C:\inetpub\FabrikamFiber.Web\bin, the directory for the product site. When prompted, it is OK to replace the existing copy of the file.

Figure 49

Deploying the instrumented assembly to production

Note: We recommend that you to reset the virtual machine after this lab given the change to the production web site for Fabrikam Fiber.

  1. Next, we will cause an exception to occur and see the resulting incident work item in TFS.

Exercise 4: Viewing Incidents in TFS

In this exercise, you will see PreEmptive Analytics in action as the instrumented application hits the exception, pushes data to the configured endpoint, and an incident is ultimately surfaced to Team Foundation Server.

  1. Launch Internet Explorer and select FF Intranet Portal from the favorites bar to load the Fabrikam Fiber intranet site.

Figure 50

Fabrikam Fiber Intranet site

  1. Select the Create New button. This will throw the exception.

Figure 51

Location of the Create New button

Figure 52

Exception caused by selecting the “Create New” button.

  1. Go back to Visual Studio. In Team Explorer – PreEmptive Analytics, select the All Incidents query. From the incident work item, you can see the stack trace at the time that the exception occurred as well as how many times the exception was experienced by customers.

Note: This incident may take a minute or two to show up, so you may need to click the Refresh button.

Figure 53

Incident view

Note: In the event that you experience trouble with PreEmptive Analytics, check the event log for more information. In addition, see the Troubleshooting section of the help file located in the PreEmptive Solutions installation folder (C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics for TFS CE\doc on the VM).

Note: While this Hands-On lab does not cover it, Incident work items are also viewable via TFS Web Access provided you have installed the PreEmptive Analytics Web Extension. If you have upgraded to TFS 2012 Update 1 or greater, an update of the PreEmptive Analytics Web Extension is also required. To get the update, go to PreEmptive Solution’s web site at Click on “My Account” and log in (or create an account if you don’t have one). The update can be found in the “Downloads” section and should take no more than a few minutes to complete.