PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide
PreEmptive Analytics for TFS
www.preemptive.com

Glossary Item Box

PreEmptive Analytics for TFS CE offers a free, lightweight way to integrate feedback-driven development processes into your development workflow. Your applications will automatically send back exception report data to your PreEmptive Analytics endpoint service as errors occur during their execution. Your PreEmptive Analytics aggregator service then collects these error reports and automatically creates or updates work items in Microsoft Team Foundation Server based on rules and thresholds you define. These work items will include the exception type, message, full stack trace, the contents of any inner exceptions, and the list of all assemblies loaded at the time of the exception, as well as the number of such exceptions received. With a small amount of additional configuration, you will also be able to see unique instance identifiers (such as the serial number of each application instance that experienced the exception) as well as comments about the error and contact information, if provided by the end user.

This guide will aid you in installing and configuring both the PreEmptive Analytics endpoint and aggregator services. You can host your endpoint services either on a dedicated machine or on your Microsoft Team Foundation server. Your aggregator service will be hosted on your Microsoft Team Foundation server. The user interface for configuring the aggregator service rules and for displaying the detailed exception data for work items created by the aggregator service is built-in to Microsoft Visual Studio 11. A stand-alone interface for configuring the aggregator service rules across all team projects is also installed alongside the aggregator service binaries.

See Also

Getting Started with PreEmptive Analytics
Getting Started with PreEmptive Analytics

Installing PreEmptive Analytics
Installing PreEmptive Analytics

Configuring your Team Projects for PreEmptive Analytics
Configuring your Team Projects for PreEmptive Analytics

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application

Examining Incidents in Team Explorer
Examining Incidents in Team Explorer

Troubleshooting
Troubleshooting

© 2012 PreEmptive Solutions. All rights reserved.


Getting Started with PreEmptive Analytics

Getting Started with PreEmptive Analytics

Glossary Item Box

Follow the topics in this Getting Started guide to quickly get up and running with PreEmptive Analytics. You will learn how to:

  • Perform a Basic Installation of PreEmptive Analytics for TFS,
  • Provision your Team Projects with PreEmptive Analytics capabilities,
  • Define Exception Sets and Rules that will guide the creation of Incident work items based on the number and type of exception report messages your applications send,
  • Add exception reporting capabilities to your applications, and
  • Examine newly-created Incident work items in Team Explorer.

See Also

Installing PreEmptive Analytics
Performing a Basic Installation

Configuring your Team Projects for PreEmptive Analytics
Provisioning Team Projects
Defining Exception Sets and Rules

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application

Examining Incidents in Team Explorer
Examining Incidents in Team Explorer


Installing PreEmptive Analytics

Installing PreEmptive Analytics

Glossary Item Box

PreEmptive Analytics can be installed in either Basic or Advanced mode. When launching PreEmptive Analytics Setup from the Team Foundation Server Configuration Center or Team Foundation Server Administration Console, Basic mode will be chosen automatically. To launch Advanced mode, you must run the setup utility (PreEmptive.Analytics.Setup.exe) directly from the Team Foundation Server installation media. Regardless of installation mode, if you wish to be able to view Incident work items via Team Foundation Server Web Access you will need to upload and activate the PreEmptive Analytics Visualizer web extension once setup is complete.

Prerequisites

  • Windows Vista, 7, Server 2008, or Server 2008 R2.
  • SQL Server 2008 (or R2) Express or higher.
  • IIS 7.0 or higher.
  • Microsoft Team Foundation Server installed and configured.

See Also

Performing a Basic Installation
Performing an Advanced Installation
Installing the Analytics Visualizer Extension for TFS Web Access


Performing a Basic Installation

Performing a Basic Installation

Glossary Item Box

When performing a Basic installation, all components will be installed to the same machine (which must be running Microsoft Team Foundation Server). 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 contain the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages). The installation must be started by a user with administrative access to the local instance of SQL Server so that the new database can be deployed. You will be asked to provide credentials for a user account with permissions to create and edit work items in the local installation of Team Foundation Server. This account must also be able to log on to the local SQL Server installation, and will be used as the Application Pool identity for the new endpoint services applications created in IIS.

Aggregator Service Configuration

On this screen, specify the account name and password for an account that will be used to run the PreEmptive Analytics aggregator service and endpoint services. This account must have permissions to create and edit work items in the local installation of Team Foundation Server. Refer to the Team Foundation Server Administration Console to locate or create an account with these privileges. This account must also be able to log on to the local SQL Server installation, and will be used as the Application Pool identity for the new endpoint web service applications created in IIS. The installer will automatically assign this account the necessary rights to access the newly-created exceptions database and to host the endpoint web services.

Installation Complete

Upon successful installation, the installer will provide you with the URL of your exception message endpoint. You will need to provide this endpoint when using the Runtime Intelligence API or when instrumenting your applications for exception reporting with PreEmptive Dotfuscator or DashO. Instrumented applications must be able to access this endpoint, so you may need to adjust firewall settings to allow your target applications to send data to this endpoint. For more information about instrumenting your applications, see the Adding Exception Reporting to a .NET Application topic.

Once you close the installer, the PreEmptive Analytics configuration utility will launch to allow you to provision team projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident work items. For more information, see the Configuring your Team Projects for PreEmptive Analytics topic.

Upload the PreEmptive Analytics visualizer extension for TFS Web Access (optional)

In order for users to view Incident work items in Team Foundation Server Web Access, a TFS administrator must upload and enable the PreEmptive Analytics visualizer extension. Follow the instructions in the Installing the Analytics Visualizer Extension for TFS Web Access topic to enable this functionality for your users.

See Also

Installing the Analytics Visualizer Extension for TFS Web Access

Configuring your Team Projects for PreEmptive Analytics
Configuring your Team Projects for PreEmptive Analytics

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application


Performing an Advanced Installation

Performing an Advanced Installation

Glossary Item Box

When performing a Advanced installation, you will have the opportunity to choose whether you wish to only install the endpoint services (Exception Endpoint Role), only the aggregator service (Exception Aggregator Role), or both (Combined Endpoint & Aggregator Role).

  • When Installing the Exception Endpoint Role, you will be able to choose a SQL Server on which to create a new database to store exception report messages, and will be able to customize the installation of the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages).
  • When Installing the Exception Aggregator Role, you will be able to customize the installation of the PreEmptive Analytics Aggregator service and configure it to retrieve exception report data from the PreEmptive Analytics endpoint services hosted on another machine.
  • When Installing the Combined Endpoint and Aggregator Role, both the PreEmptive Analytics endpoint services and the PreEmptive Analytics Aggregator service will be installed on the local machine, similar to performing a Basic installation. However, you will have the ability to customize each component as described above.

See Also

Installing the Exception Endpoint Role
Installing the Exception Aggregator Role
Installing the Combined Endpoint and Aggregator Role
Installing the Analytics Visualizer Extension for TFS Web Access


Installing the Exception Endpoint Role

Installing the Exception Endpoint Role

Glossary Item Box

When installing the Exception Aggregator Role, a new database will be created in an instance of SQL Server to store exception report data and a new website will be created in IIS to contain the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages). The installation must be started by a user with administrative access to the target instance of SQL Server so that the new database can be deployed. You will be asked to provide account credentials to be used as the Application Pool identity for the new endpoint services applications created in IIS, and you will choose whether to also use this account for Integrated Security authentication to the target instance of SQL Server, or whether to provide a login and password for use with SQL Authentication.

Exception Endpoint IIS Configuration

On this screen, you must specify the account name and password to be used as the IIS Application Pool identity for the PreEmptive Analytics endpoint services. If you choose to use Integrated Security for communication between the endpoint services and SQL Server, this account will also be granted permissions to log on to the target instance of SQL Server.

Next, you may specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IIS Website into which the PreEmptive Analytics endpoint services will be installed. If the website already exists, the endpoint services applications will be added to the root of the website and its port binding will not be modified. If the website does not exist, it will be created and a binding will be added to listen on the port specified. You may also choose to specify the location on disk into which the PreEmptive Analytics program files will be installed, or you may leave the default selection.

Exception Endpoint SQL Configuration

On this screen, you may specify the hostname of the SQL Server instance in which a new database will be created to store exception report message data. You may also specify the name of the database to be used. Ensure that there is not an existing database with the same name on the selected instance of SQL Server.

Next, decide whether Integrated Security or SQL Authentication should be used for communication between the endpoint services and the SQL Server database. If using Integrated Security, the IIS Application Pool user account specified in the Exception Endpoint IIS Configuration screen will be used. Depending on your choice, the installer will create a new Integrated Security or SQL Authentication login on the target SQL Server instance if one does not exist, and the specified login will be granted permission to use the newly-created database.

Installation Complete

Upon successful installation, the installer will provide you with the URL of your exception message endpoint. You will need to provide this endpoint when using the Runtime Intelligence API or when instrumenting your applications for exception reporting with PreEmptive Dotfuscator or DashO. Instrumented applications must be able to access this endpoint, so you may need to adjust firewall settings to allow your target applications to send data to this endpoint. For more information about instrumenting your applications, see the Adding Exception Reporting to a .NET Application topic.

The installer will also provide you with the URL of your endpoint query service. An Exception Aggregator service running on another machine will communicate with this endpoint query service to retrieve exception data in order to create Incident work items. During the installation of the Exception Aggregator Role on the remote machine, you will be asked to provide this URL. For more information, see the Installing the Exception Aggregator Role topic.

See Also

Installing the Exception Aggregator Role

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application


Installing the Exception Aggregator Role

Installing the Exception Aggregator Role

Glossary Item Box

When installing the Exception Aggregator Role, the PreEmptive Analytics Aggregator service will be installed and set to start automatically. You will be asked to provide credentials for a user account with permissions to create and edit work items in the local installation of Team Foundation Server.

Aggregator Service Configuration

On this screen, specify the account name and password for an account that will be used to run the PreEmptive Analytics aggregator service and endpoint services. This account must have permissions to create and edit work items in the local installation of Team Foundation Server. Refer to the Team Foundation Server Administration Console to locate or create an account with these privileges. You may also choose to specify the location on disk into which the PreEmptive Analytics program files will be installed, or you may leave the default selection.

Next, you must specify the URL of the endpoint query service running on another machine which has already had the Exception Endpoint Role installed. The aggregator service will communicate with the provided endpoint query service to retrieve exception data in order to create Incident work items. During the installation of the Exception Endpoint Role on the remote machine, you will be provided with this URL. For more information, see the Installing the Exception Endpoint Role topic.

Installation Complete

Once you close the installer, the PreEmptive Analytics configuration utility will launch to allow you to provision team projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident work items. For more information, see the Configuring your Team Projects for PreEmptive Analytics topic.

Upload the PreEmptive Analytics visualizer extension for TFS Web Access (optional)

In order for users to view Incident work items in Team Foundation Server Web Access, a TFS administrator must upload and enable the PreEmptive Analytics visualizer extension. Follow the instructions in the Installing the Analytics Visualizer Extension for TFS Web Access topic to enable this functionality for your users.

See Also

Installing the Exception Endpoint Role
Installing the Analytics Visualizer Extension for TFS Web Access

Configuring your Team Projects for PreEmptive Analytics
Configuring your Team Projects for PreEmptive Analytics


Installing the Combined Endpoint and Aggregator Role

Installing the Combined Endpoint and Aggregator Role

Glossary Item Box

When installing the Combined Exception Endpoint & Aggregator Role, all components will be installed to the same machine. The PreEmptive Analytics Aggregator service will be installed and set to start automatically. You will be asked to provide credentials for a user account with permissions to create and edit work items in the local installation of Team Foundation Server. A new database will be created in an instance of SQL Server to store exception report data and a new website will be created in IIS to contain the PreEmptive Analytics endpoint message & query services (which receive exception report messages from instrumented applications and provide access to stored messages). The installation must be started by a user with administrative access to the target instance of SQL Server so that the new database can be deployed. You will be asked to provide account credentials to be used as the Application Pool identity for the new endpoint services applications created in IIS, and you will choose whether to also use this account for Integrated Security authentication to the target instance of SQL Server, or whether to provide a login and password for use with SQL Authentication.

Aggregator Service Configuration

On this screen, specify the account name and password for an account that will be used to run the PreEmptive Analytics aggregator service and endpoint services. This account must have permissions to create and edit work items in the local installation of Team Foundation Server. Refer to the Team Foundation Server Administration Console to locate or create an account with these privileges. You may also choose to specify the location on disk into which the PreEmptive Analytics program files will be installed, or you may leave the default selection.

Exception Endpoint IIS Configuration

On this screen, you must specify the account name and password to be used as the IIS Application Pool identity for the PreEmptive Analytics endpoint services. If you choose to use Integrated Security for communication between the endpoint services and SQL Server, this account will also be granted permissions to log on to the target instance of SQL Server.

Next, you may specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IIS Website into which the PreEmptive Analytics endpoint services will be installed. If the website already exists, the endpoint services applications will be added to the root of the website and its port binding will not be modified. If the website does not exist, it will be created and a binding will be added to listen on the port specified.

Exception Endpoint SQL Configuration

On this screen, you may specify the hostname of the SQL Server instance in which a new database will be created to store exception report message data. You may also specify the name of the database to be used. Ensure that there is not an existing database with the same name on the selected instance of SQL Server.

Next, decide whether Integrated Security or SQL Authentication should be used for communication between the endpoint services and the SQL Server database. If using Integrated Security, the IIS Application Pool user account specified in the Exception Endpoint IIS Configuration screen will be used. Depending on your choice, the installer will create a new Integrated Security or SQL Authentication login on the target SQL Server instance if one does not exist, and the specified login will be granted permission to use the newly-created database.

Installation Complete

Upon successful installation, the installer will provide you with the URL of your exception message endpoint. You will need to provide this endpoint when using the Runtime Intelligence API or when instrumenting your applications for exception reporting with PreEmptive Dotfuscator or DashO. Instrumented applications must be able to access this endpoint, so you may need to adjust firewall settings to allow your target applications to send data to this endpoint. For more information about instrumenting your applications, see the Adding Exception Reporting to a .NET Application topic.

Once you close the installer, the PreEmptive Analytics configuration utility will launch to allow you to provision team projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident work items. For more information, see the Configuring your Team Projects for PreEmptive Analytics topic.

Upload the PreEmptive Analytics visualizer extension for TFS Web Access (optional)

In order for users to view Incident work items in Team Foundation Server Web Access, a TFS administrator must upload and enable the PreEmptive Analytics visualizer extension. Follow the instructions in the Installing the Analytics Visualizer Extension for TFS Web Access topic to enable this functionality for your users.

See Also

Installing the Analytics Visualizer Extension for TFS Web Access

Configuring your Team Projects for PreEmptive Analytics
Configuring your Team Projects for PreEmptive Analytics

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application


Installing the Analytics Visualizer Extension for TFS Web Access

Installing the Analytics Visualizer Extension for TFS Web Access
www.preemptive.com

Glossary Item Box

In order for users to view Incident work items in Team Foundation Server Web Access, a TFS administrator must upload and enable the PreEmptive Analytics visualizer extension via the TFS Web Access administration page.

Upload the PreEmptive Analytics visualizer extension for TFS 11 Web Access

  1. Navigate to the TFS Web Access site in your browser.
  2. Click the Administer Team Foundation Server tile (or the gear icon in the top-right of the page if the tile is not visible).
  3. Select the Extensions tab and choose Install New.
  4. Click the Browse... button and select the PreEmptiveAnalyticsVisualizer.zip file from the TFS\Web subfolder within the PreEmptive Analytics installation directory (by default, C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics CE).
  5. Click OK to upload and install the extension.
  6. Click the Enable button next to the PreEmptive Analytics Aggregator Visualizer extension.
  7. Click OK in the dialog prompting you to grant access to the extension.


Configuring your Team Projects for PreEmptive Analytics

Configuring your Team Projects for PreEmptive Analytics

Glossary Item Box

To integrate PreEmptive Analytics with your team projects, you must connect the PreEmptive Analytics aggregator service to your local Team Foundation Server instance and provision team projects for use with PreEmptive Analytics. Provisioned team projects can define subscriptions to receive exception report data for instrumented applications and rules to define how and when to create Incident work items from these exception reports.

Prerequisites

  • Windows Vista, 7, Server 2008, or Server 2008 R2.
  • SQL Server 2008 (or R2) Express or higher (optionally with SQL Server Reporting Services installed).
  • Team Foundation Server (optionally with Reporting Services integration installed).
  • Visual Studio or Team Explorer installed.
  • PreEmptive Analytics endpoint services deployed.
  • PreEmptive Analytics aggregator service installed and running.

See Also

Provisioning Team Projects
Defining Exception Sets and Rules


Provisioning Team Projects

Provisioning Team Projects

Glossary Item Box

The PreEmptive Analytics aggregator service connects to your local Team Foundation Server installation to create and modify Incident work items in response to configured rules which can include criteria such as the type and quantity of exception reports received. To begin using this functionality, you must launch the Configuration Utility which will be used to connect to your Team Foundation Server and provision your team projects for use with PreEmptive Analytics.

PreEmptive Analytics CE allows you to connect to a single Team Foundation Server project collection, and to provision up to two team projects for use with PreEmptive Analytics. To provision additional team projects, or to integrate with multiple team project collections or Team Foundation Server instances, you will need to purchase PreEmptive Analytics for TFS directly from PreEmptive Solutions. For more information, please visit www.preemptive.com/pa or e-mail solutions@preemptive.com.

Verify the aggregator service installation

  1. From the Start menu, launch the PreEmptive Analytics Configuration utility.
  2. The Aggregator Configuration URL will be displayed. If there is an error connecting to the Aggregator Configuration service, it must be corrected before you can proceed. See the Troubleshooting the Analytics Aggregator Service topic for steps in solving issues with the aggregator service.

Connect to team project collections

  1. Select the Team Foundation Servers node and click the + button.
  2. Choose one of the configured servers from the dropdown, or add a new Team Foundation Server by clicking the Servers... button.
  3. If the logged-in user does not have permissions to access the desired Team Foundation Server or team project collection, click the Use Different Credentials link and supply credentials with the desired permissions.
  4. Select the desired team project collection and click Connect.
    Once you have created rules that reference this team project collection, you will not be able to delete it or change the Name or Fully Qualified URL fields without first removing all the rules that reference it.

Provision team projects for PreEmptive Analytics

Team projects must be provisioned to be used with PreEmptive Analytics. In the Team Projects list, each team project in the collection is displayed, along with its provisioning status. During provisioning, the Incident work item type and sample PreEmptive Analytics reports will be imported into the project template. The project will also be configured with settings that the PreEmptive Analytics Visual Studio extension needs in order to be able to configure exception sets and rules. To provision a team project for use with PreEmptive Analytics, click the Apply link next to the desired team project. Modifications made during the provisioning process can be rolled back by selecting the Remove link next to any provisioned team project.

See Also

Troubleshooting
Troubleshooting the Analytics Aggregator Service


Defining Exception Sets and Rules

Defining Exception Sets and Rules

Glossary Item Box

Subscriptions define the mapping between an application instrumented with exception reporting capabilities, a team project in which to create work items based on exceptions the application experiences, and the rules that govern the creation of such work items. Subscriptions can have multiple rules, each of which define a set of conditions under which a work item will be created including criteria such as the number and type of exception reports received, and the time period in which they must be received in order to trigger the creation of a work item. These settings are configured across all provisioned projects using the Configuration Utility installed alongside the PreEmptive Analytics aggregator service, or on a per-project basis via the PreEmptive Analytics Aggregator Visualizer extension for Visual Studio.

PreEmptive Analytics CE allows you to create a single subscription for each team project, and to define up to three rules for each subscription. In addition, only a single rule type (ErrorCountOverTime) is included with PreEmptive Analytics CE. PreEmptive Analytics for TFS, purchased directly from PreEmptive Solutions, contains the ability to define an unlimited number of subscriptions and rules and includes additional rule types. For more information, please visit www.preemptive.com/pa or e-mail solutions@preemptive.com.

Create exception rules

  1. Launch Visual Studio and navigate to the Team Explorer pane. Provisioned team projects will show a PreEmptive Analytics entry.
  2. Click the PreEmptive Analytics node to open the PreEmptive Analytics hub.
  3. In the Settings group, click Configure. This will launch the rule configuration window.
  4. Click on the General node in the left navigation. The Aggregator Configuration URL will be displayed. If there is an error connecting to the Aggregator Configuration service, it must be corrected before you can proceed. See the Troubleshooting the Analytics Aggregator Service topic for steps in solving issues with the aggregator service.
  5. Select the Exception Sets node in the left navigation. By default, there is a single exception set defined named AllExceptions which matches all incoming exceptions. You can create other exception sets which match one or more exception types as follows:
    1. Click the + icon to add a new, empty exception set. Provide a name for this exception set in the Name field.
    2. In the Exceptions grid, add a new row for each exception type you would like to track. Fill in the fully-qualified exception type name (such as System.Net.WebException or java.io.FileNotFoundException) in the Exception Type column, and provide a name for this exception type (typically the unqualified exception type name) in the Name column.
      PreEmptive Analytics does not attempt to traverse the inheritance hierarchy of reported exceptions. For example, adding a rule for System.ApplicationException will not automatically match reported exceptions that are sub-types of System.ApplicationException.
    Once you have created rules that reference this exception set, you will not be able to delete it or change the Name field without first removing all the rules that reference it.
  6. Select the Subscriptions node in the left navigation, and click the + icon to add a new, empty subscription.
  7. Provide a name for this subscription in the Name field.

  8. In the Identity group box, supply the Company and Application ID values you used when instrumenting your application to send exception reporting data. For more information on how to add and configure exception reporting in your applications, see the Adding Exception Reporting to a .NET Application topic.

  9. Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change the duration for which the aggregator service will keep detailed data for each received exception.
  10. In the Team Foundation Server group box, optionally specify the area path you wish to use for the created work items in the Area Path field.

  11. In the Rules grid, you can create rules to be applied to exception reports received from the application you specified above:

    1. Choose the exception set you wish to use for this rule in the Exception Set Name dropdown. All exceptions that are included in this set can potentially trigger the execution of the rule.
    2. In the Span Minutes column, specify how far back from the current time the aggregator service should query for exception report messages. Each time the aggregator service checks for exception new exception reports, if there are sufficient exception reports to meet the threshold criteria between the time of the check and the x minutes prior, a work item will be created. The default is one day (1440 minutes).
    3. In the Threshold column, specify the threshold value you wish to use, such as the number of exceptions (of the types defined in your exception set) that must be received to trigger the creation of a work item.
  12. You can add additional subscriptions to process exception reporting data from other applications, or from the same application using a different Area Path by selecting the Subscriptions node and clicking the + icon to create additional subscriptions.

See Also

Adding Exception Reporting to a .NET Application
Adding Exception Reporting to a .NET Application

Troubleshooting
Troubleshooting the Analytics Aggregator Service


Adding Exception Reporting to a .NET Application

Adding Exception Reporting to a .NET Application

Glossary Item Box

Applications must be instrumented with exception reporting code in order to send exception reports to your PreEmptive Analytics endpoint. Adding exception reporting code to compiled .NET applications is easy using either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics, a free tool included in Microsoft Visual Studio.

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics includes a Walkthrough section which will describe how you can easily add exception reporting code to your .NET assembly. For a full description of the exception reporting instrumentation capabilities of PreEmptive Dotfuscator and Analytics, please see the Exception Reporting section of the Getting Started guide.

Prerequisites

  • Visual Studio with PreEmptive Dotfuscator and Analytics OR PreEmptive Dotfuscator Professional installed.
  • PreEmptive Analytics endpoint services deployed.
  • PreEmptive Analytics aggregator service deployed.


Examining Incidents in Team Explorer

Examining Incidents in Team Explorer

Glossary Item Box

PreEmptive Analytics exception reporting includes a special work item type named Incident to contain information about exceptions that match the rules defined for the PreEmptive Analytics aggregator service. It also includes the PreEmptive Analytics Aggregator Visualizer extension which includes a Team Explorer pane that allows you to view Incident items and reports and configure the aggregator service rules.

Prerequisites

  • Visual Studio or Team Explorer installed.
  • PreEmptive Analytics endpoint services deployed.
  • TFS project provisioned for PreEmptive Analytics via the Configuration Utility.
  • Exception report messages sent from application instrumented with exception reporting.
  • PreEmptive Analytics aggregator service deployed and rules defined for instrumented application.

The PreEmptive Analytics hub

When a team project has been provisioned for PreEmptive Analytics via the PreEmptive Analytics Configuration Utility, the PreEmptive Analytics hub will appear as an option in the Team Explorer pane of Visual Studio. The PreEmptive Analytics hub provides access to Incident items and administrative reports concerning the frequency and number of open Incident items. It also allows you to configure exception sets and rules for the project in question. Unlike the PreEmptive Analytics Configuration Utility which must be executed by a user with full administrative access to the Team Foundation Server, the configuration interface provided by the PreEmptive Analytics hub in Visual Studio can be operated by any user that has been granted administrative rights to the team project in question, and he or she will only be able to configure rules for that project. For more information about configuring exception sets and rules, see the Defining Exception Sets and Rules topic.

The Incident work item type

The Incident work item contains a number of useful fields which will provide insight into the types of exceptions your instrumented applications are experiencing in production.

  • The Title field is automatically populated with the name of the rule that caused the incident to be created, the type of the exception, and the name of the application that experienced the exception.
  • The Classification section shows the company name, application name, and application version as they were configured during instrumentation of the application that experienced the exception.
  • The Exception tab shows the full stack trace of the exception that caused the work item to be created. Inner exceptions are also shown below the top-level exception, if available.
  • The Incident Details tab shows unique data that may have accompanied each exception report message:
    • If the application was configured to send unique instance identifiers during instrumentation, the Instance ID column will contain the identifier of the application instance that experienced the exception.
    • If configured during instrumentation and if provided by the user that experienced the exception, the Contact and Comment columns may contain user-supplied contact information and user-supplied comments about the exception.
    • The Host Info column contains information about the machine on which the exception occurred.
    • The Loaded Components column contains the assemblies or components that were loaded in the application at the time the exception occurred.
  • In the Metrics section, the number of individual exception reports received that matched the rule is shown in the Raw Exception Count field.
  • If the application was configured to send unique instance identifiers during instrumentation, the Exception Count By Instance field will show the number of different instances of the application (as defined by unique serial number or other unique instance identifier) that have experienced the exception.
  • The Accept New Data dropdown allows you to turn off further updates to this work item. When this setting is enabled, as new exceptions are received that continue to match the rule the aggregated counts in the work item will be updated and additional detail data will be added to the Incident Details view. If you switch this setting to No, no further updates to the work item or incident details will be made and any exception messages that continue to match the rule will be ignored. You can switch this setting back to Yes at any time to resume updating the work item and incident details. Any past exception reports (up to the configured Data Retention Days setting) that were received during the time the Accept New Data value was set to No will be immediately processed and added to the work item.

See Also

Configuring your Team Projects for PreEmptive Analytics
Defining Exception Sets and Rules


Troubleshooting

Troubleshooting

Glossary Item Box

Starting Point: Open the Windows Event Viewer

Depending on the operating system, access the Windows Event Viewer as follows:

  • Windows 7 or Vista:
  1. Click Start.
  2. In the Search programs and files text box, type eventvwr.msc and press the Enter key.
  • Windows XP or Windows Server:
  1. Click Start > Run...
  2. In the dialog, type eventvwr.msc in the text box.
  3. Click OK.

Viewing the PreEmptive Event Log

  1. In the tree view to the left, expand Applications and Services Logs.
  2. Click PreEmptive.

Errors occurring in the Endpoint Services will have a value of PreEmptiveAnalytics in the Source column of the Event Viewer.

Errors occurring in the Aggregator Service will have a value of Aggregator in the Source column of the Event Viewer.

Troubleshooting Concepts

Troubleshooting the Analytics Endpoint Services

Use this section to troubleshoot issues receiving, persisting, or retrieving exception message data using the PreEmptive Analytics Endpoint Services.

Troubleshooting the Analytics Aggregator Service

Use this section to troubleshoot issues with creating or updating work items in TFS.

See Also

Troubleshooting the Analytics Endpoint Services
Troubleshooting the Analytics Aggregator Service


Troubleshooting the Analytics Endpoint Services

Troubleshooting the Analytics Endpoint Services

Glossary Item Box

Overview

This section provides troubleshooting information related to the PreEmptive Analytics Endpoint Services. These services are responsible for receiving, persisting, and exposing exception message data.

Issues involving the endpoint message service

Error Solution
HTTP Error 503. The service is unavailable.
  1. Click Start.
  2. In the Search Programs and files textbox, type inetmgr
  3. Expand Sites.
  4. Expand the web site which contains the PreEmptive Analytics endpoint services (Team Foundation Server, by default).
  5. Right-click message > Manage Application > Advanced Settings...
  6. Note the name of the Application Pool.
  7. Click Cancel.
  8. Click Application Pools.
  9. Find the Application Pool name in the list.
  10. If the Status is not Started, right-click and choose Start.
  11. If the .NET Framework Version is not v4.0, right-click and choose Basic Settings... From the .NET Framework version drop down, choose the current version of the .NET Framework v4.0.
  12. If the Identity is not set to the account name you chose during installation, right-click and choose Advanced Settings... In the Identity field, click the ... button and choose the correct account name. You may be asked to provide the password for the account.
  13. Click OK.

System.Data.SqlClient.SqlException (0x80131904): Cannot open database "Exceptions" requested by the login. The login failed.

Login failed for user 'message'.
  1. Using SQL Server Management Studio, make sure you can connect to your PreEmptive Analytics Exceptions database using the account name and password you specified during installation.
  2. Open a new connection to your PreEmptive Analytics Exceptions database using an administrator account. The 'message' user should belong to the 'pa_message' role.
HTTP Error 401.1 (Access Denied)
  1. Click Start.
  2. In the Search Programs and files textbox type inetmgr
  3. Expand Sites.
  4. Expand the web site which contains the PreEmptive Analytics endpoint services (Team Foundation Server, by default).
  5. Click message.
  6. Double-click Authentication.
  7. Select Anonymous Authentication, and then click Enable in the Actions pane.

Issues involving the endpoint query service

Error Solution
HTTP Error 503. The service is unavailable.
  1. Click Start.
  2. In the Search Programs and files textbox, type inetmgr
  3. Expand Sites.
  4. Expand the web site which contains the PreEmptive Analytics endpoint services (Team Foundation Server, by default).
  5. Right-click analytics > Manage Application > Advanced Settings...
  6. Note the name of the Application Pool.
  7. Click Cancel.
  8. Click Application Pools.
  9. Find the Application Pool name in the list.
  10. If the Status is not Started, right-click and choose Start.
  11. If the .NET Framework Version is not v4.0, right-click and choose Basic Settings...
  12. From the .NET Framework version drop down, choose the current version of the .NET Framework v4.0.
  13. If the Identity is not set to the account name you chose during installation, right-click and choose Advanced Settings... In the Identity field, click the ... button and choose the correct account name. You may be asked to provide the password for the account.
  14. Click OK.

System.Data.SqlClient.SqlException (0x80131904): Cannot open database "Exceptions" requested by the login. The login failed.

Login failed for user 'data'.
  1. Using SQL Server Management Studio, make sure you can connect to your PreEmptive Analytics Exceptions database using the account name and password you specified during installation.
  2. Open a new connection to your PreEmptive Analytics Exceptions database using an administrator account. The 'data' user should belong to the 'pa_data' role.
HTTP status code 401.1 Access Denied
  1. Click Start.
  2. In the Search Programs and files textbox type inetmgr
  3. Expand Sites.
  4. Expand the web site which contains the PreEmptive Analytics endpoint services (Team Foundation Server, by default).
  5. Click analytics.
  6. Double-click Authentication.
  7. Choose how you wish to authenticate requests to your raw data service:
    • If you wish to allow anonymous access to your raw data service, select Anonymous Authentication, and then click Enable in the Actions pane, OR
    • If you wish to protect access to your raw data service, select Basic Authentication, and then click Enable in the Actions pane. When using Basic authentication you should serve your endpoint raw data service over SSL only, as credentials will be transmitted in plain text.


Troubleshooting the Analytics Aggregator Service

Troubleshooting the Analytics Aggregator Service

Glossary Item Box

This section provides troubleshooting information related to the PreEmptive Analytics Aggregator Service. This service is responsible for sending requests to the Query Service to get recent exception data, manage criteria (rules) for exception types, and connecting to TFS to create work items.

Issues experienced by the aggregator service are logged in the Windows Event Log, in the PreEmptive node of the Applications and Services Logs section. Examining this log can often provide assistance in resolving aggregator service issues.

Problem | Potential Cause | Solution
Work Items are not showing up as expected. | Raw data service endpoint is not running. | See the Troubleshooting the Analytics Endpoint Services topic.
Raw data service endpoint is not accessible from the machine hosting the aggregator service.
  1. Attempt to ping the server hosting the Raw Data service from the machine hosting the Aggregator service.
  2. Check firewall settings on both machines.
  3. Ensure you are able to browse to the raw data service endpoint URL (If you used the default values during installation, this should follow the form http://<endpoint services machine name>/analytics/FaultQuery.svc.)
  4. If you are able to browse to the endpoint URL but see an HTTP error code, reference the Troubleshooting the Analytics Endpoint Services topic with any HTTP Error code displayed.
Raw data service is experiencing an error. | See the Troubleshooting the Analytics Endpoint Services topic.
Raw data service endpoint is using basic authentication and credentials in the aggregator service .config file are missing or incorrect.
  1. Open the PreEmptive.Analytics.Aggregator.exe.config file from within the Service subdirectory of the PreEmptive Analytics aggregator service install directory (by default, C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics CE) using a text editor.
  2. Locate the <appSettings> element and specify the user name and password used to access the endpoint raw data service in the EndpointUserName and EndpointPassword values.
Raw data service endpoint is using basic authentication and login name in the aggregator service .config file is not an authorized user in IIS.
  1. Click Start.
  2. In the Search Programs and files textbox, type inetmgr
  3. Expand Sites.
  4. Expand Default Web Site.
  5. Click analytics.
  6. Double-click .NET Authorization Rules.
  7. Ensure the EndpointUserName in the PreEmptive.Analytics.Aggregator.exe.config file is listed (or is a member of a listed group.)
Raw data service endpoint is using basic authentication, aggregator service is configured to connect using http URI scheme (not https.) | Using basic authentication over SSL is highly recommended, as credentials are transmitted in plain text. However, if your configuration requires the PreEmptive Analytics endpoint raw data service to use basic authentication over unsecured HTTP instead of SSL, you will need to locate the <binding> element named BasicSecurity and change its security mode value from Transport to TransportCredentialOnly.
Aggregator service is not running.
  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator entry and choose Run.
Aggregator service is not running under an account with permissions to create and edit work items in Team Foundation Server.

The Analytics aggregator service must be configured to execute using an account with permissions to create and edit work items in Team Foundation Server.

  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator Service entry and choose Properties.
  3. Select the Log On tab.
  4. Specify the User ID and password of the current TFS Service Account. If the account is a local account, specify the full account name (e.g. COMPUTER\TfsService rather than simply .\TfsService or TfsService).
  5. Click OK.

To determine the name of an account with permissions to create and edit work items in Team Foundation Server, launch the Team Foundation Server Administration Console and click on the Application Tier node. Click on Group Membership, and locate an account that is a member of a group with permissions to create and edit work items, such as the Team Foundation Administrators group.
Rule criteria not being met.

Using SQL Server Management Studio, connect to the exceptions database being used to persist exception data. Query against the Exceptions table, and verify the number of exception report messages exceeds the threshold, and have been persisted within the time span specified in the rule.
Exceptions received not in rule’s exception set. | Inspect the exception set assigned to the rule and ensure the exceptions being received are included, or create a new exception set that includes the exceptions being received and assign it to the rule.
Team project is not provisioned for PreEmptive Analytics. | See the Provision team projects section of the Provisioning Team Projects topic.
TFS Work item query does not include Incident work items. | Ensure that the Incident work item type is included in the TFS work item query you wish to use for viewing work items created by the Aggregator service.
PreEmptive Analytics node is not visible in Team Explorer. | Team project is not provisioned for PreEmptive Analytics. | See the Provision team projects section of the Provisioning Team Projects topic.
Configuration Utility or VS extension can’t connect to configuration service. Aggregator service is not running.
  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator entry and choose Run.
Aggregator service credentials are incorrect.
  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator entry and choose Properties.
  3. Select the Log On tab.
  4. Verify the User ID and re-enter the password of the service account you wish to use. If the account is a local account, specify the full account name (e.g. COMPUTER\TfsService rather than simply .\TfsService or TfsService).
  5. Click OK.
  6. If you changed the service account, you must also grant it permissions to host the configuration service on port 80:
    1. Launch an elevated command prompt and execute the command netsh http del urlacl url=http://+:80/AggregatorConfigurationService/ to remove permissions from any other accounts. If running this command returns an error, it simply means that no other accounts had been granted permissions to host the service and you should proceed to the next step.
    2. Execute the command netsh http add urlacl url=http://+:80/AggregatorConfigurationService/ user="<Service Account User Name>" to grant permissions for the new service account to host the aggregator configuration service.
Aggregator service account does not have Log on as a Service rights.
  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator entry and choose Properties.
  3. Select the Log On tab.
  4. Verify the User ID and re-enter the password of the service account you wish to use. If the account is a local account, specify the full account name (e.g. COMPUTER\TfsService rather than simply .\TfsService or TfsService).
  5. Click OK. If permissions to log on as a service were not previously assigned to that account, you will be notified and they will be granted automatically.
Aggregator service account does not have permission to host configuration service on port 80.
  1. Click Start.
  2. In the Search Programs and files textbox, type eventvwr.msc
  3. Under Applications and Services Logs, select the PreEmptive node.
  4. Look for an error log entry with the phrase "HTTP could not register URL http://+:80/AggregatorConfigurationService/. Your process does not have access rights to this namespace".
  5. If such an entry exists, you must grant the service account permissions to host the configuration service on port 80:
    1. Launch an elevated command prompt and execute the command netsh http del urlacl url=http://+:80/AggregatorConfigurationService/ to remove permissions from any other accounts. If running this command returns an error, it simply means that no other accounts had been granted permissions to host the service and you should proceed to the next step.
    2. Execute the command netsh http add urlacl url=http://+:80/AggregatorConfigurationService/ user="<Service Account User Name>" to grant permissions for the new service account to host the aggregator configuration service.
Aggregator configuration service is being blocked by a firewall. | Launch the configuration tool for your firewall. Allow the PreEmptive.Analytics.Aggregator.exe application to accept incoming connections on port 80. The PreEmptive.Analytics.Aggregator.exe application is located in the Service subfolder within the PreEmptive Analytics installation directory (by default, C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics CE)
Aggregator service raw data connection is configured incorrectly, or raw data service is inaccessible.
  1. Open the PreEmptive.Analytics.Aggregator.exe.config file from within the Service subdirectory of the PreEmptive Analytics aggregator service install directory (by default, C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics CE) using a text editor.
  2. Locate the <endpoint> element and verify that the value of the address attribute is a valid exception endpoint query service URL.

If this is configured correctly:

  1. Attempt to ping the server hosting the raw data service endpoint from the machine running the aggregator service.
  2. Check firewall settings on both machines.
  3. Ensure you are able to browse to the raw data service endpoint URL (If you used the default values during installation, this should follow the form http://<endpoint services machine name>/analytics/FaultQuery.svc.)
  4. If you are able to browse to the endpoint URL but see an HTTP error code, reference the Troubleshooting the Analytics Endpoint Services topic with any HTTP Error code displayed.
(For VS extension) Aggregator service is not accessible from the machine running Visual Studio.
  1. Attempt to ping the server hosting the Aggregator service from the machine running Visual Studio.
  2. Check firewall settings on both machines.
  3. Ensure you are able to browse to the aggregator configuration service URL (This should follow the form http://<aggregator service machine name>/AggregatorConfigurationService/.)
Provisioning a team project fails. Aggregator service is not running under an account with permissions to create and edit work items in Team Foundation Server.

The Analytics aggregator service must be configured to execute using an account with permissions to create and edit work items in Team Foundation Server.

  1. Launch the Control Panel, and open the Administrative Tools folder. Double-click the Services icon.
  2. Right-click the PreEmptive Analytics Aggregator Service entry and choose Properties.
  3. Select the Log On tab.
  4. Specify the User ID and password of the current TFS Service Account. If the account is a local account, specify the full account name (e.g. COMPUTER\TfsService rather than simply .\TfsService or TfsService).
  5. Click OK.

To determine the name of an account with permissions to create and edit work items in Team Foundation Server, launch the Team Foundation Server Administration Console and click on the Application Tier node. Click on Group Membership, and locate an account that is a member of a group with permissions to create and edit work items, such as the Team Foundation Administrators group.
PreEmptive Analytics hub is not visible in Visual Studio. | Team project is not provisioned for PreEmptive Analytics. | See the Provision team projects for PreEmptive Analytics section of the Provisioning Team Projects topic.
Visual Studio extension cache must be refreshed. | Launch an instance of the Visual Studio Command Prompt and execute the command devenv.exe /setup to refresh the extension cache.
Sample reports are not working correctly. TFS data warehouse has not run.

The TFS data warehouse process executes every two hours by default. You can wait for the process to occur, or manually execute the data warehouse process by following the instructions in the Manually Process the Data Warehouse and Analysis Services Cube for Team Foundation Server topic of the Team Foundation Server documentation.
Report data is cached.
  1. Launch Internet Explorer and browse to your TFS reports site (typically, http://<Your TFS Server>/Reports/).
  2. Click on the TfsReports folder to open it, then open your team project collection folder, your team project folder, and finally the PreEmptive Analytics folder.
  3. Hover over the report in question and click to open the dropdown menu. Click Manage.
  4. Click Processing Options in the left navigation.
  5. Select the Always run this report with the most recent data radio button, and underneath it select Do not cache temporary copies of this report.
  6. Click Apply at the bottom of the page.
In TFS Web Access, the Incident work item does not show the exception information or an error is displayed. | PreEmptive Analytics Aggregator Visualizer extension is disabled or not installed. | Follow the installation process in the Installing the Analytics Visualizer Extension for TFS Web Access topic. Ensure you enable the extension after it is installed.

Viewing the Aggregator Service Debug Console

Occasionally, a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to the Windows event log. In these cases, it can be useful to view the debug output of the aggregator service itself using the aggregator service debug console. Running the service in debug mode should only be done to debug specific issues - once the issues are solved, do not continue to run the service in debug mode. Instead, exit the debug console and start the PreEmptive Analytics Aggregator Service from the Services console directly.

  1. Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console.
  2. From the command prompt, change directory to the Service subfolder within the PreEmptive Analytics installation directory (by default, C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics CE).
  3. Execute the command PreEmptive.Analytics.Aggregator.exe /debug to launch the debug console.
  4. Click the Start button to start the service in debug mode, and watch the Trace log window for debugging messages.
  5. When finished, click the Stop button and close the debug console. Restart the PreEmptive Analytics Aggregator Service from the Services console.

See Also

Troubleshooting the Analytics Endpoint Services

Installing PreEmptive Analytics
Installing the Analytics Visualizer Extension for TFS Web Access

Configuring your Team Projects for PreEmptive Analytics
Provisioning Team Projects
Defining Exception Sets and Rules