55
Professional Edition User's Guide Version 1.3

PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Embed Size (px)

Citation preview

Page 1: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Professional Edition

Users GuideVersion 13

copy 2015 PreEmptive Solutions LLCAll rights reserved

Document Version 13-20151125wwwpreemptivecom

TRADEMARKS

PreEmptive Analytics PreEmptive Analytics for TFS Dotfuscator DashO the PreEmptive Analytics for TFS logo the PreEmptive Solutionslogo the Dotfuscator logo and the DashO logo are trademarks of PreEmptive Solutions LLC

NETtrade Team Foundation Servertrade and Visual Studiotrade are trademarks of Microsoft Inc

Java is a trademark of Oracle Inc

All other trademarks are property of their respective owners

THIS PUBLICATION IS PROVIDED ldquoAS ISrdquo WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITEDTO IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT

THIS PUBLICATION COULD CONTAIN TYPOGRAPHIC ERRORS ANDOR TECHNICAL INACCURACIES UPDATES AND MODIFICATIONS MAY BEMADE TO THIS DOCUMENT ANDOR SUPPORTING SOFTWARE AT ANY TIME

PreEmptive Solutions LLC has intellectual property rights relating to technology embodied in this product In particular and withoutlimitation these intellectual property rights may include one or more US patents or pending patent applications in the US andor othercountries

This product is distributed under licenses restricting its use copying distribution and decompilation No part of this product may bereproduced in any form by any means without prior written authorization of PreEmptive Solutions LLC

1 Table of Contents1 Table of Contents 3-4

2 Overview 5

3 Installing PreEmptive Analytics for TFS 6

31 Prerequisites 6-7

32 Planning a Production Installation 7-10

33 Performing a Basic (single-machine) Installation 11-12

34 Performing an Advanced Installation 12

341 Installing the Endpoint 12-13

342 Installing the Aggregator 13-14

343 Installing the Endpoint and Aggregator Together 14-16

344 Securing the Components 16-19

35 Installing the Visual Studio Components 19

36 Installing the Web Components 19-20

4 Configuring PreEmptive Analytics for TFS 21

41 Provisioning Team Projects 21

42 Defining Exception Sets and Rules 22-23

421 Rule Types 23-24

422 Possible Surprises 24-25

43 Configuring the New Data Check Interval 25-26

44 Configuring Custom Data Attachment Limits 26

45 Making URL changes after installation 27

451 Change Aggregator Service URL 27-33

452 Change Fault Query Service URL 34

5 Adding Exception Reporting to an Application 35

6 Examining Incidents in Team Explorer 36-37

7 Upgrading PreEmptive Analytics for TFS 38

71 Validating the Upgrade 38

8 Troubleshooting 39-40

81 Troubleshooting Installation 41

82 Troubleshooting the Endpoint 41-44

83 Troubleshooting the Aggregator 45-51

PreEmptive Analytics for TFS User Guide 3

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 Monitoring 52

10 Maintenance 53

11 Index 54-55

PreEmptive Analytics for TFS User Guide 4

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 OverviewPreEmptive Analytics for TFS allows you to integrate feedback-driven development processes into your developmentworkflow By analyzing and aggregating exceptions reported by your production applications and automatically creating TFSwork items PreEmptive Analytics for TFS gives you access to unprecedented levels of incident data right where you need itndash in Visual Studio TFS Web and Reporting Services

Your instrumented applications will automatically send exception report data to your PreEmptive Analytics for TFSinstallation as errors occur during execution PreEmptive Analytics for TFS will automatically create or update work items inMicrosoft Team Foundation Server based on rules and thresholds you define These work items include details about theexception type message full stack trace the contents of any inner exceptions and the list of all assemblies loaded at thetime of the exception as well as the number of such exceptions received With a small amount of additional configurationyou will also be able to see unique instance identifiers (such as the serial number of each application instance thatexperienced the exception) as well as comments about the error and contact information if provided by the end user

Components

PreEmptive Analytics for TFS is made up of five individual components that are distributed via two installers Thosecomponents are shown in dark blue in the diagram below

Endpoint Provides a web service that accepts exception messages and stores them for evaluation This can beexposed to the public internet if needed

Aggregator Periodically queries the Endpoint and evaluates new data against rules which are configured by amachine-local configuration (admin) utility andor by a project-specific (limited) version of the utility installed as partof the Visual Studio Components

Visual Studio Components Provides a Visual Studio control for viewing stack traces and incident details a customTeam Explorer pane for accessing the work items created by PreEmptive Analytics for TFS and a lightweight versionof the configuration (admin) utility for configuring project-specific settings

Web Components Provides a control for viewing stack traces and incident details in TFS Web Access

Reports Provides reports (for each TFS project) that summarize the work items created by PreEmptive Analytics forTFS for that project

Please see Installing PreEmptive Analytics for TFS for more information about how and where to install these components

PreEmptive Analytics for TFS User Guide 5

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 2: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

copy 2015 PreEmptive Solutions LLCAll rights reserved

Document Version 13-20151125wwwpreemptivecom

TRADEMARKS

PreEmptive Analytics PreEmptive Analytics for TFS Dotfuscator DashO the PreEmptive Analytics for TFS logo the PreEmptive Solutionslogo the Dotfuscator logo and the DashO logo are trademarks of PreEmptive Solutions LLC

NETtrade Team Foundation Servertrade and Visual Studiotrade are trademarks of Microsoft Inc

Java is a trademark of Oracle Inc

All other trademarks are property of their respective owners

THIS PUBLICATION IS PROVIDED ldquoAS ISrdquo WITHOUT WARRANTY OF ANY KIND EITHER EXPRESS OR IMPLIED INCLUDING BUT NOT LIMITEDTO IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT

THIS PUBLICATION COULD CONTAIN TYPOGRAPHIC ERRORS ANDOR TECHNICAL INACCURACIES UPDATES AND MODIFICATIONS MAY BEMADE TO THIS DOCUMENT ANDOR SUPPORTING SOFTWARE AT ANY TIME

PreEmptive Solutions LLC has intellectual property rights relating to technology embodied in this product In particular and withoutlimitation these intellectual property rights may include one or more US patents or pending patent applications in the US andor othercountries

This product is distributed under licenses restricting its use copying distribution and decompilation No part of this product may bereproduced in any form by any means without prior written authorization of PreEmptive Solutions LLC

1 Table of Contents1 Table of Contents 3-4

2 Overview 5

3 Installing PreEmptive Analytics for TFS 6

31 Prerequisites 6-7

32 Planning a Production Installation 7-10

33 Performing a Basic (single-machine) Installation 11-12

34 Performing an Advanced Installation 12

341 Installing the Endpoint 12-13

342 Installing the Aggregator 13-14

343 Installing the Endpoint and Aggregator Together 14-16

344 Securing the Components 16-19

35 Installing the Visual Studio Components 19

36 Installing the Web Components 19-20

4 Configuring PreEmptive Analytics for TFS 21

41 Provisioning Team Projects 21

42 Defining Exception Sets and Rules 22-23

421 Rule Types 23-24

422 Possible Surprises 24-25

43 Configuring the New Data Check Interval 25-26

44 Configuring Custom Data Attachment Limits 26

45 Making URL changes after installation 27

451 Change Aggregator Service URL 27-33

452 Change Fault Query Service URL 34

5 Adding Exception Reporting to an Application 35

6 Examining Incidents in Team Explorer 36-37

7 Upgrading PreEmptive Analytics for TFS 38

71 Validating the Upgrade 38

8 Troubleshooting 39-40

81 Troubleshooting Installation 41

82 Troubleshooting the Endpoint 41-44

83 Troubleshooting the Aggregator 45-51

PreEmptive Analytics for TFS User Guide 3

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 Monitoring 52

10 Maintenance 53

11 Index 54-55

PreEmptive Analytics for TFS User Guide 4

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 OverviewPreEmptive Analytics for TFS allows you to integrate feedback-driven development processes into your developmentworkflow By analyzing and aggregating exceptions reported by your production applications and automatically creating TFSwork items PreEmptive Analytics for TFS gives you access to unprecedented levels of incident data right where you need itndash in Visual Studio TFS Web and Reporting Services

Your instrumented applications will automatically send exception report data to your PreEmptive Analytics for TFSinstallation as errors occur during execution PreEmptive Analytics for TFS will automatically create or update work items inMicrosoft Team Foundation Server based on rules and thresholds you define These work items include details about theexception type message full stack trace the contents of any inner exceptions and the list of all assemblies loaded at thetime of the exception as well as the number of such exceptions received With a small amount of additional configurationyou will also be able to see unique instance identifiers (such as the serial number of each application instance thatexperienced the exception) as well as comments about the error and contact information if provided by the end user

Components

PreEmptive Analytics for TFS is made up of five individual components that are distributed via two installers Thosecomponents are shown in dark blue in the diagram below

Endpoint Provides a web service that accepts exception messages and stores them for evaluation This can beexposed to the public internet if needed

Aggregator Periodically queries the Endpoint and evaluates new data against rules which are configured by amachine-local configuration (admin) utility andor by a project-specific (limited) version of the utility installed as partof the Visual Studio Components

Visual Studio Components Provides a Visual Studio control for viewing stack traces and incident details a customTeam Explorer pane for accessing the work items created by PreEmptive Analytics for TFS and a lightweight versionof the configuration (admin) utility for configuring project-specific settings

Web Components Provides a control for viewing stack traces and incident details in TFS Web Access

Reports Provides reports (for each TFS project) that summarize the work items created by PreEmptive Analytics forTFS for that project

Please see Installing PreEmptive Analytics for TFS for more information about how and where to install these components

PreEmptive Analytics for TFS User Guide 5

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 3: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

1 Table of Contents1 Table of Contents 3-4

2 Overview 5

3 Installing PreEmptive Analytics for TFS 6

31 Prerequisites 6-7

32 Planning a Production Installation 7-10

33 Performing a Basic (single-machine) Installation 11-12

34 Performing an Advanced Installation 12

341 Installing the Endpoint 12-13

342 Installing the Aggregator 13-14

343 Installing the Endpoint and Aggregator Together 14-16

344 Securing the Components 16-19

35 Installing the Visual Studio Components 19

36 Installing the Web Components 19-20

4 Configuring PreEmptive Analytics for TFS 21

41 Provisioning Team Projects 21

42 Defining Exception Sets and Rules 22-23

421 Rule Types 23-24

422 Possible Surprises 24-25

43 Configuring the New Data Check Interval 25-26

44 Configuring Custom Data Attachment Limits 26

45 Making URL changes after installation 27

451 Change Aggregator Service URL 27-33

452 Change Fault Query Service URL 34

5 Adding Exception Reporting to an Application 35

6 Examining Incidents in Team Explorer 36-37

7 Upgrading PreEmptive Analytics for TFS 38

71 Validating the Upgrade 38

8 Troubleshooting 39-40

81 Troubleshooting Installation 41

82 Troubleshooting the Endpoint 41-44

83 Troubleshooting the Aggregator 45-51

PreEmptive Analytics for TFS User Guide 3

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 Monitoring 52

10 Maintenance 53

11 Index 54-55

PreEmptive Analytics for TFS User Guide 4

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 OverviewPreEmptive Analytics for TFS allows you to integrate feedback-driven development processes into your developmentworkflow By analyzing and aggregating exceptions reported by your production applications and automatically creating TFSwork items PreEmptive Analytics for TFS gives you access to unprecedented levels of incident data right where you need itndash in Visual Studio TFS Web and Reporting Services

Your instrumented applications will automatically send exception report data to your PreEmptive Analytics for TFSinstallation as errors occur during execution PreEmptive Analytics for TFS will automatically create or update work items inMicrosoft Team Foundation Server based on rules and thresholds you define These work items include details about theexception type message full stack trace the contents of any inner exceptions and the list of all assemblies loaded at thetime of the exception as well as the number of such exceptions received With a small amount of additional configurationyou will also be able to see unique instance identifiers (such as the serial number of each application instance thatexperienced the exception) as well as comments about the error and contact information if provided by the end user

Components

PreEmptive Analytics for TFS is made up of five individual components that are distributed via two installers Thosecomponents are shown in dark blue in the diagram below

Endpoint Provides a web service that accepts exception messages and stores them for evaluation This can beexposed to the public internet if needed

Aggregator Periodically queries the Endpoint and evaluates new data against rules which are configured by amachine-local configuration (admin) utility andor by a project-specific (limited) version of the utility installed as partof the Visual Studio Components

Visual Studio Components Provides a Visual Studio control for viewing stack traces and incident details a customTeam Explorer pane for accessing the work items created by PreEmptive Analytics for TFS and a lightweight versionof the configuration (admin) utility for configuring project-specific settings

Web Components Provides a control for viewing stack traces and incident details in TFS Web Access

Reports Provides reports (for each TFS project) that summarize the work items created by PreEmptive Analytics forTFS for that project

Please see Installing PreEmptive Analytics for TFS for more information about how and where to install these components

PreEmptive Analytics for TFS User Guide 5

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 4: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

9 Monitoring 52

10 Maintenance 53

11 Index 54-55

PreEmptive Analytics for TFS User Guide 4

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 OverviewPreEmptive Analytics for TFS allows you to integrate feedback-driven development processes into your developmentworkflow By analyzing and aggregating exceptions reported by your production applications and automatically creating TFSwork items PreEmptive Analytics for TFS gives you access to unprecedented levels of incident data right where you need itndash in Visual Studio TFS Web and Reporting Services

Your instrumented applications will automatically send exception report data to your PreEmptive Analytics for TFSinstallation as errors occur during execution PreEmptive Analytics for TFS will automatically create or update work items inMicrosoft Team Foundation Server based on rules and thresholds you define These work items include details about theexception type message full stack trace the contents of any inner exceptions and the list of all assemblies loaded at thetime of the exception as well as the number of such exceptions received With a small amount of additional configurationyou will also be able to see unique instance identifiers (such as the serial number of each application instance thatexperienced the exception) as well as comments about the error and contact information if provided by the end user

Components

PreEmptive Analytics for TFS is made up of five individual components that are distributed via two installers Thosecomponents are shown in dark blue in the diagram below

Endpoint Provides a web service that accepts exception messages and stores them for evaluation This can beexposed to the public internet if needed

Aggregator Periodically queries the Endpoint and evaluates new data against rules which are configured by amachine-local configuration (admin) utility andor by a project-specific (limited) version of the utility installed as partof the Visual Studio Components

Visual Studio Components Provides a Visual Studio control for viewing stack traces and incident details a customTeam Explorer pane for accessing the work items created by PreEmptive Analytics for TFS and a lightweight versionof the configuration (admin) utility for configuring project-specific settings

Web Components Provides a control for viewing stack traces and incident details in TFS Web Access

Reports Provides reports (for each TFS project) that summarize the work items created by PreEmptive Analytics forTFS for that project

Please see Installing PreEmptive Analytics for TFS for more information about how and where to install these components

PreEmptive Analytics for TFS User Guide 5

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 5: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

2 OverviewPreEmptive Analytics for TFS allows you to integrate feedback-driven development processes into your developmentworkflow By analyzing and aggregating exceptions reported by your production applications and automatically creating TFSwork items PreEmptive Analytics for TFS gives you access to unprecedented levels of incident data right where you need itndash in Visual Studio TFS Web and Reporting Services

Your instrumented applications will automatically send exception report data to your PreEmptive Analytics for TFSinstallation as errors occur during execution PreEmptive Analytics for TFS will automatically create or update work items inMicrosoft Team Foundation Server based on rules and thresholds you define These work items include details about theexception type message full stack trace the contents of any inner exceptions and the list of all assemblies loaded at thetime of the exception as well as the number of such exceptions received With a small amount of additional configurationyou will also be able to see unique instance identifiers (such as the serial number of each application instance thatexperienced the exception) as well as comments about the error and contact information if provided by the end user

Components

PreEmptive Analytics for TFS is made up of five individual components that are distributed via two installers Thosecomponents are shown in dark blue in the diagram below

Endpoint Provides a web service that accepts exception messages and stores them for evaluation This can beexposed to the public internet if needed

Aggregator Periodically queries the Endpoint and evaluates new data against rules which are configured by amachine-local configuration (admin) utility andor by a project-specific (limited) version of the utility installed as partof the Visual Studio Components

Visual Studio Components Provides a Visual Studio control for viewing stack traces and incident details a customTeam Explorer pane for accessing the work items created by PreEmptive Analytics for TFS and a lightweight versionof the configuration (admin) utility for configuring project-specific settings

Web Components Provides a control for viewing stack traces and incident details in TFS Web Access

Reports Provides reports (for each TFS project) that summarize the work items created by PreEmptive Analytics forTFS for that project

Please see Installing PreEmptive Analytics for TFS for more information about how and where to install these components

PreEmptive Analytics for TFS User Guide 5

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 6: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

3 Installing PreEmptive Analytics for TFSThe PreEmptive Analytics Endpoint and Aggregator are both installed by a single installer(PreEmptiveAnalyticsProSetupexe) which can operate in either Basic or Advanced mode Basic mode isintended primarily for evaluation purposes as it installs all the components on a single machine This installer alsoplaces the Web Components in the same location as the Aggregator From there they must be manually installedin TFS Web Access

In Advanced mode you can choose to install the Endpoint separately from the Aggregator which is the moretypical installation approach for production use

The Visual Studio Components are distributed by a second installer (PreEmptiveAnalyticsVisualStudioexe) The Visual Studio Components should be installed on all machines that have Visual Studio and will be used toaccess team projects that have work items generated by PreEmptive Analytics for TFS

31 Prerequisites

Software requirements

All components

Windows Vista 7 8 10 Server 2008 Server 2008 R2 Server 2012 or Server 2012 R2

NET 40 or 45 (NET 40 will be installed automatically if neither version is present)

Endpoint

SQL Server 2008 2008 R2 2012 or 2014 or SQL Express 2008 2012 or 2014

IIS 70 75 80 or 100

Optional A valid SSL certificate

Aggregator

An accessible Team Foundation Server (2010 2012 2013 or 2015)

An installed and operating PreEmptive Analytics for TFS Endpoint

PreEmptive Analytics for TFS User Guide 6

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 7: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Visual Studio Components

An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator

Visual Studio 2010 2012 2013 or 2015

Specific user account requirementsThe list below enumerates the access requirements needed for PA for TFS installation and operation A single account canbe used to satisfy all requirements

Installation requirements

A Windows user account with rights to install software on the Endpoint and Aggregator machines

A Windows user account with administrative access to the SQL Server instance for the Endpoint This user must beused to run the Endpoint installer

A TFS account with TFS administrative access to install the PreEmptive Web Components

Operational requirements

A Windows user account to be used by the Endpoint to access SQL Server This user does not need to haveadministrator access to SQL Server

If performing a basic install the installer will use the same account that you supply for TFS

If performing an advanced install you will specify this user account explicitly

A Windows user account to be used as the Application Pool identity for the new Endpoint services applications createdin IIS

A Windows user account to run the PreEmptive Analytics Aggregator Service with permissions to

Write to the file system

Access the network

Create and edit work items in Team Foundation Server

Optional Query and update the TFS Maximum Attachment Size setting (only members of the ldquoTeam FoundationAdministratorsrdquo group have access to this)

Network access requirementsInstrumented applications must have access to the Endpoint The default port provided by the Endpoint installer is8000 but can be changed in the installer or reconfigured after install Port 443 will be used for SSL

The Endpoint must have access to the SQL Server instance where the Endpoint database resides

The Aggregator Service must be able to access the Endpoint using the same port configured for instrumentedapplications (See the first bullet)

The Aggregator Service must have access to TFS

The PA for TFS configuration utility must have access to the Aggregator Configuration Service (installed along with theAggregator Service) via port 80

Visual Studio installs on individual user machines need to have access to the PA for TFS Aggregator ConfigurationService on port 80

32 Planning a Production Installation

PreEmptive Analytics for TFS User Guide 7

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 8: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Endpoint and AggregatorThe Endpoint and Aggregator together provide the core feature of PreEmptive Analytics for TFS accepting exceptionmessages processing those messages through the configured rules and creating TFS work items based on the ruleresults That feature is split across two separate runtime components in order to support different network topologiesespecially corporate networks that are split into a DMZ and an internal network

The Endpoint is designed to run in a DMZ it is a small web service that only accepts messages and stores them in adatabase It never sendspushes that data anywhere else so it does not require a firewall hole to reach the internalnetwork It can respond to queries (ie from the Aggregator) to deliver new messages to the internal network uponrequest Note that it is not necessary to run it in a DMZ it can be run on the same machine as the Aggregator if thatmeets your needs

The Endpoint must be network-reachable by your production instrumented applications Its hostURL should be long-livedand stable because it will be built into your instrumented production applications

The Endpoint requires IIS and access to a SQL Server (or SQL Express) database

The Aggregator is designed to run inside the internal network It is a Windows service that periodically queries theEndpoint for new data then processes that data through the configured rules and then creates or updates work items inTFS as needed The Aggregator is also responsible for configuring individual TFS projects to use PreEmptive Analytics forTFS It creates a local time-limited cache of the data it processes and also caches some state-tracking data in TFS as workitem attachments

The Aggregator must have network access (for a web service call) to the Endpoint must have network access to the TFSserver and must run as a user that has sufficient rights to configure TFS team projects and create and update work itemsin those projects The Aggregator is also able to query and update the TFS Maximum Attachment Size setting (as a userconvenience) but only if it is running as a user with TFS administrative rights

One Aggregator can support multiple TFS instances and multiple team projects in each instance

Recommendations

We recommend starting with the Endpoint and Aggregator on separate hosts If any of your applications ndash now or in thefuture ndash run outside your network the Endpoint should be in the DMZ If not the Endpoint can be installed inside theinternal network In either case it should have a stable hostnameURL and it should usually be on a dedicated host TheAggregator can usually be installed on the same host as TFS but if you have scalability or TFS performance concerns youmay want to install it on its own machine

There are certain scenarios that might require multiple Endpoint instances andor multiple Aggregator instances Thesescenarios should be very rare please contact Support if you believe you might need such a topology

PreEmptive Analytics for TFS User Guide 8

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 9: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Hardware recommendations

The hardware requirements for the Endpoint and Aggregator are generally modest Our testing demonstrated that thesystem can operate normally under a load of 60 envelopes per second if the Endpoint and Aggregator are on separate VMs(with the Aggregator on the same VM as the test TFS instance) with these specifications

Endpoint Intel Pentium(R) D 280GHz 200GB RAM

Aggregator Six-Core AMD Opteron(tm) 2439 SE 279GHz (2 processors) 200GB RAM

60 envelopes per second is a very high volume for most contexts An envelope is a batch of messages usually sent by theclient every 10 seconds (depending on client platform and application configuration) A typical client will send messageswhen the application starts when it shuts down and during execution so in the worst case an application that is onlyinstrumented to send exceptions will send 3 envelopes per application run If the Endpoint is receiving 60 envelopes persecond that translates to roughly 200 application runs per second (60 10 3)

One important variable is the number and complexity of configured rules and subscriptions A system with manysubscriptions each with multiple rules will require more resources than the example provided above It is also possible tocreate custom rule types that execute arbitrary code while evaluating rules performance in such scenarios depends heavilyon the custom implementation

Storage requirements are typically modest depend heavily on both the rate of message delivery and the amount of customdata included with each exception report To provide a baseline a production (mobile) application that was runapproximately 90000 times generating approximately 5000 exceptions with moderate custom data used less than100MB of storage on the Endpoint

Note that the Aggregator also has a configuration setting (Data Retention Days) that determines how long it shouldpreserve its data cache That setting is 30 days by default but can be changed as described in Defining Exception Setsand Rules The Endpoint does not have a similar setting but the database has stored procedures that can be manually runto clean up old envelopes if storage size becomes an issue

For users wishing to be cautious in large-volume environments we recommend putting the Aggregator on a machine that isequivalent to one of your TFS servers

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents) created byPreEmptive Analytics for TFS from within Visual Studio They also provide convenients features for accessing those workitems and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access work itemscreated by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from the Community Edition(CE) of PreEmptive Analytics for TFS Installing the Pro version of these components will uninstall the CE versionautomatically Please ensure you do so to avoid version conflicts between CE Visual Studio Components and a ProAggregator

Please see Installing the Visual Studio Components for instructions

Web Components

The Web Components provide a custom control that is necessary to view work items created by PreEmptive Analytics forTFS from within TFS Web Access The Aggregator installer will put the Web Components on that same machine but fromthere they must be manually installed into TFS Web Access (This is a limitation of TFS Web Access) See Installing theWeb Components for instructions

PreEmptive Analytics for TFS User Guide 9

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 10: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Reports

The Reports do not have to be administratively installed They will be deployed to Reporting Services automatically eachtime the configuration (admin) utility is used to configure a team project to work with PreEmptive Analytics for TFS so longas the TFS instance is configured to use Reporting Services

PreEmptive Analytics for TFS User Guide 10

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 11: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

33 Performing a Basic (single-machine) Installation

What to ExpectWhen performing a Basic installation all components will be installed to the same machine (which must be runningMicrosoft Team Foundation Server) The PreEmptive Analytics Aggregator service will be installed and set to startautomatically A new database will be created in your local instance of SQL Server to store exception report dataand a new website will be created in IIS to contain the PreEmptive Analytics endpoint message amp 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 sothat 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 inTeam Foundation Server

This account must also be able to log on to the local SQL Server installation and will be used as theApplication Pool identity for the new endpoint services applications created in IIS

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the PreEmptiveAnalytics aggregator service and endpoint services This account must have permissions to create and edit workitems in the local installation of Team Foundation Server Refer to the Team Foundation Server AdministrationConsole to locate or create an account with these privileges This account must also be able to log on to the localSQL Server installation and will be used as the Application Pool identity for the new endpoint web serviceapplications created in IIS The installer will automatically assign this account the necessary rights to access thenewly-created exceptions database and to host the endpoint web services

Installation CompleteUpon successful installation the installer will provide you with the URL of your exception message endpoint Youwill need to provide this endpoint when using the PreEmptive Analytics API or when instrumenting yourapplications for exception reporting with PreEmptive Dotfuscator or DashO Instrumented applications must beable to access this endpoint so you may need to adjust firewall settings to allow your target applications to senddata to this endpoint For more information about instrumenting your applications see the Adding ExceptionReporting to an Application topic

Once you close the installer the PreEmptive Analytics configuration utility will launch to allow you to provisionteam projects for PreEmptive Analytics and to define rules and subscriptions to guide the creation of Incident workitems For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

PreEmptive Analytics for TFS User Guide 11

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 12: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

Upload the Web Components (optional)In order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustupload and enable the PreEmptive Analytics Web Components Follow the instructions in the Installing the WebComponents Components topic to enable this functionality for your users

34 Performing an Advanced InstallationWhen performing a Advanced installation you choose whether to install only the endpoint services only theaggregator service or both the endpoint and aggregator services

When Installing the Endpoint you choose a SQL Server instance in which to create a new database (or reusean existing database) to store exception report messages and customize the installation of the PreEmptiveAnalytics endpoint message amp query services (which receive exception report messages from instrumentedapplications and provide access to stored messages)

When Installing the Aggregator you customize the installation of the PreEmptive Analytics Aggregatorservice and configure it to retrieve exception report data from the PreEmptive Analytics endpoint serviceshosted on another machine

When Installing the Endpoint and Aggregator Together both the PreEmptive Analytics endpoint services andthe PreEmptive Analytics Aggregator service are installed on the local machine similar to performing a Basicinstallation However you will have the ability to customize each component as described above

341 Installing the Endpoint

What to ExpectInstalling the Endpoint creates a new database in an instance of SQL Server to store exception report data (orreuses an existing exception database) and creates a website in IIS to host the PreEmptive Analytics for TFSendpoint message amp query services (which receive exception report messages from instrumented applications andprovide access to stored messages)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the database can be deployedreused

You will be asked to provide account credentials to be used as the Application Pool identity for the newEndpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

PreEmptive Analytics for TFS User Guide 12

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 13: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not bemodified When the website does not exist it will be created and a binding will be added to listen on the portspecified

Finally specify the location on disk into which the PreEmptive Analytics program files will be installed

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created or wherean existing exception database exists to store exception report message data Specify the name of thedatabase to be used

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Exception Endpoint IIS Configuration screen will be used The installer will create a newIntegrated Security or SQL Authentication login on the target SQL Server instance if one does not exist and thespecified login will be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

The installer also displays the URL of your endpoint query service An Aggregator service running on anothermachine will communicate with this endpoint query service to retrieve exception data in order to create Incidentwork items During the installation of the Aggregator on the remote machine you will be asked to provide thisURL For more information see the Installing the Aggregator topic

342 Installing the Aggregator

What to ExpectInstalling the Aggregator creates the PreEmptive Analytics for TFS Aggregator service and sets it to startautomatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

PreEmptive Analytics for TFS User Guide 13

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 14: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

Next specify the URL of the endpoint query service running on another machine where the Endpoint is installedand running The aggregator service will communicate with the provided endpoint query service to retrieveexception data in order to create Incident work items When the Endpoint was installed the URL was provided Formore information see the Installing the Endpoint topic

Installation CompleteOnce you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

343 Installing the Endpoint and Aggregator TogetherWhen installing the Endpoint and Aggregator together all components will be installed to the same machine ThePreEmptive Analytics for TFS Aggregator service will be installed and set to start automatically at Windows startup

You will be asked to provide credentials for a user account with permissions to create and edit work items inTeam Foundation Server

A new database will be created in an instance of SQL Server to store exception report data (or an existingdatabase reused)

The installation must be started by a user with administrative access to the target instance of SQL Server sothat the new database can be deployed (or the existing database reused)

A new website will be created in IIS to contain the endpoint message amp query services (which receivesexception report messages from instrumented applications and provides access to stored messages)

You will be asked to provide account credentials to be used as the Application Pool identity for the newendpoint services applications created in IIS

You will choose whether to also use this account for Integrated Security authentication to the target instanceof SQL Server or whether to provide a login and password for use with SQL Authentication

Aggregator Service ConfigurationOn this screen specify the account name and password for an account that will be used to run the Aggregatorservice This account must have permissions to create and edit work items in the Team Foundation Server Referto the Team Foundation Server Administration Console to locate or create an account with these privileges Specifythe location on disk into which the PreEmptive Analytics program files will be installed

PreEmptive Analytics for TFS User Guide 14

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 15: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Endpoint IIS ConfigurationOn this screen specify the account name and password to be used as the IIS Application Pool identity for thePreEmptive Analytics for TFS Endpoint services When you choose to use Integrated Security for communicationbetween the endpoint services and SQL Server this account will also be granted permissions to log on to thetarget instance of SQL Server

Next specify the name of the IIS Application Pool that will be used to host the endpoint services and select the IISwebsite into which the PreEmptive Analytics endpoint services will be installed When the website already existsthe endpoint services applications will be added to the root of the website and its port binding will not be modifiedWhen the website does not exist it will be created and a binding will be added to listen on the port specified

Endpoint SQL ConfigurationOn this screen specify the hostname of the SQL Server instance in which a new database will be created to storeexception report message data Specify the name of the database to be used Ensure that there is not an existingdatabase with the same name on the selected instance of SQL Server

Next select either Integrated Security or SQL Authentication to be used for communication between the endpointservices and the SQL Server database When using Integrated Security the IIS Application Pool user accountspecified in the Endpoint IIS Configuration screen will be used The installer will create a new IntegratedSecurity or SQL Authentication login on the target SQL Server instance if one does not exist and the specified loginwill be granted permission to use the newly-created database

Installation CompleteAt completion the installer displays the URL of your exception message endpoint Specify this endpoint URL whenusing the PreEmptive Analytics API or when instrumenting your applications for exception reporting withPreEmptive Dotfuscator or DashO Instrumented applications must be able to reach this endpoint and you mayneed to adjust firewall settings to allow your target applications to send data to this endpoint For moreinformation about instrumenting your applications see the Adding Exception Reporting to an Application topic

Once you close the installer the PreEmptive Analytics for TFS configuration utility launches Use this utility toprovision team projects for PreEmptive Analytics for TFS and to define rules and subscriptions to guide the creationof Incident work items For more information see the Configuring PreEmptive Analytics for TFS topic

Visual Studio Components

The Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenients features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

Please see Installing the Visual Studio Components for instructions

PreEmptive Analytics for TFS User Guide 15

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 16: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Upload the Web Components (optional)To view Incident work items in TFS Web Access a TFS administrator must upload and enable the PreEmptiveAnalytics for TFS Web Components Follow the instructions in the Installing the Web Components topic to enablethis functionality for your users

344 Securing the ComponentsThis guide shows how to configure PreEmptive Analytics for TFS to use authentication and encrypted connections The reader is assumed to be familiar with IIS and with the PreEmptive Analytics for TFS components andarchitecture

Configuring the Endpoint and Fault Query Service for SSLThis step configures the endpoint and Fault Query Service such that they support SSL connections It is possibleto configure each service independently (eg if you require SSL only on the endpoint but not on the Fault QueryService it can be configured that way)

IIS Configuration

1 Install the certificate on the IIS instance that is hosting the endpoint (directions for this are IIS versionspecific and are independent of PreEmptive Analytics for TFSmdashthe configurer is assumed to be familiar withthe process)

2 Ensure the certificate is either signed by a Certificate Authority (CA) that clients trust by default or (eg ifyou are testing) that clients are configured to trust the certificate

3 Add an https binding for the PreEmptive Analytics Endpoint site in IIS Use the certificate that wasinstalled above

4 In IIS modify the SSL settings for the Fault Query Service (ie the analytics webapp) and Endpoint(message webapp) as needed For example you can choose to require SSL for the Endpoint and theFaultQuery service

5 Verify that any firewalls are configured to allow inbound traffic on the configured ports for the configuredprotocols

Checkpoint

If IIS is configured correctly you should now be able to access both the endpoint and the Fault Query Service viaHTTPS URLs from a remote client browser For example

Going to https[hostname][port]messageEndpointashx should result in ldquo405 Method not allowedrdquo

Going to https[hostname][port]analyticsFaultQuerysvc should show the service page

Additionally instrumented applications now ought to be able to send analytics messages to the endpoint using SSLon port 443

Proceed to the next step to finish configuring the Fault Query Service

Fault Query Service Configuration

Next to configure the Fault Query Service to use Transport Mode security update the analytics webappswebconfig file

PreEmptive Analytics for TFS User Guide 16

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 17: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

1 Add the following binding under the webHttpBinding element

ltbinding name=secureWebHttp maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=None gt

ltsecuritygt

ltbindinggt

2 Add the following endpoint under the service element

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttp

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

Configuring the Aggregator to use SSL when connecting to theFault Query ServiceThis step configures the Aggregatorrsquos Fault Query Service client to connect to the service using SSL

1 Stop the aggregator service

2 Edit the PreEmptiveAnalyticsAggregatorexeconfig (located here by default CProgram Files(x86)PreEmptive SolutionsPreEmptive Analytics for TFSService)

3 Ensure there is a binding defined that uses Transport security mode like this

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Nonegt

ltsecuritygt

ltbindinggt

4 Replace the endpoint in the client section with this

ltendpoint address=https[hostname][port]analyticsFaultQuerysvc

behaviorConfiguration=webHttpBehavior

binding=webHttpBinding

bindingConfiguration=BasicSecurity

contract=PreEmptiveAnalyticsAggregatorProxyIFaultQuerygt

5 Start the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 This can be verified using a tool like Fiddler Web Debugger (which canbe configured to decrypt HTTPS traffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe loggedrequests from the aggregator should indicate a 202 response code

PreEmptive Analytics for TFS User Guide 17

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 18: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Configuring the Fault Query Service for AuthenticationThis step configures the Fault Query Service to require a user name and password for client connections It isassumed (and highly recommended) that the Fault Query Service and Aggregator have already been configured touse SSL Further it is recommended that the Fault Query Service be configured to require SSL (this can be donein IIS)

1 Make sure IIS has the required authentication module installed (eg Basic Authentication) On Windows 8this is done via AddRemove Windows Features

2 In IIS manager configure the analytics webapp to use the authentication you want (eg BasicAuthentication)

3 In the web config file for analytics update the binding to reflect the credential type you are using

ltbinding name=secureWebHttpWithAuth maxReceivedMessageSize=2000000gt

ltreaderQuotas maxArrayLength=3000 maxNameTableCharCount=100000 maxBytesPerRead=1000000gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basic gt

ltsecuritygt

ltbindinggt

ltendpoint address=

binding=webHttpBinding

behaviorConfiguration=restEPBehavior

bindingConfiguration=secureWebHttpWithAuth

contract=PreEmptiveComponentsFaultQuerySchemaIFaultQuerygt

4 Setup the account and credentials you want to use for accessing the service This depends on whichauthentication mode you have chosen

Checkpoint

If IIS and authentication is configured correctly you should now only be able to access the fault query servicefrom a client browser if you are authenticated For example if you are using Basic Authentication you should beprompted for credentials when you visit

https[hostname][port]analyticsFaultQuerysvc

Once successfully authenticated you should see the service page

Configuring the Aggregator to use Authentication for the FaultQuery ServiceThis step configures the Aggregatorrsquos Fault Query Service client to provide credentials to the service

1 Stop the aggregator service

2 In the aggregator servicersquos app config file update the binding to reflect the credential type you are using (itmust match the type defined in the service configuration)

ltbinding name=BasicSecurity maxBufferPoolSize=2147483647 maxBufferSize=2147483647

maxReceivedMessageSize=2147483647gt

ltsecurity mode=Transportgt

lttransport clientCredentialType=Basicgt

ltsecuritygt

ltbindinggt

PreEmptive Analytics for TFS User Guide 18

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 19: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

3 Add the credentials to the aggregators app configuration file

ltappSettingsgt

ltadd key=EndpointUserName value=YourUsername gt

ltadd key=EndpointPassword value=YourPassword gt

ltappSettingsgt

4 Restart the aggregator service

Checkpoint

If the aggregator and Fault Query Service are configured correctly the aggregator should be connecting to theFault Query Service using SSL on port 443 The aggregator should be providing credentials using the configuredmode This can be verified using a tool like Fiddler Web Debugger (which can be configured to decrypt HTTPStraffic) or by looking at the IIS web logs for the Fault Query Servicemdashthe logged requests from the aggregatorshould indicate a 202 response code for authenticated authorized clients and a 401 for unauthorized clients

Configuring the Aggregatorrsquos Configuration Service to use SSLNot currently supported

Authentication for the Aggregatorrsquos Configuration ServiceNot currently supported

35 Installing the Visual Studio ComponentsThe Visual Studio Components provide custom controls that are necessary to view the work items (incidents)created by PreEmptive Analytics for TFS from within Visual Studio They also provide convenient features foraccessing those work items and for viewing and editing project-specific rules and settings

The Visual Studio Components must be installed in every instance of Visual Studio that will be used to access workitems created by PreEmptive Analytics for TFS

Note that Visual Studio 2012 and above come pre-installed with the Visual Studio Components from theCommunity Edition (CE) of PreEmptive Analytics for TFS Installing the Pro version of these components willuninstall the CE version automatically Please ensure you do so to avoid version conflicts between CE VisualStudio Components and a Pro Aggregator

To install the Visual Studio Components

1 Execute the Visual Studio Components Installer (PreEmptiveAnalyticsVisualStudioexe)

2 Accept the license agreement and click Install

3 Close and re-open Visual Studio

36 Installing the Web ComponentsIn order for users to view Incident work items in Team Foundation Server Web Access a TFS administrator mustfollow the following instructions

PreEmptive Analytics for TFS User Guide 19

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 20: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2012 or later

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 tileis not visible)

3 Select the Extensions tab and choose Install New

4 Click the Browse button and select the PreEmptiveAnalyticsVisualizerzip file from the Web subfolderwithin the PreEmptive Analytics installation directory (by default [ProgramFilesFolder]PreEmptiveSolutionsPreEmptive Analytics)

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

Upload the PreEmptive Analytics Web Components for Web Accessin TFS 2010

1 Browse to the the Web subfolder within the PreEmptive Analytics installation directory (by default[ProgramFilesFolder]PreEmptive SolutionsPreEmptive Analytics)

2 Locate the files PreEmptiveAnalyticsAggregatorWebControl100dll andPreEmptiveAnalyticsVisualizerwicc

3 Copy these two files to the Application TierWeb AccessWebApp_DataCustomControls subfolder withinthe Team Foundation Server 2010 installation directory (by default [ProgramFilesFolder]Microsoft TeamFoundation Server 2010)

PreEmptive Analytics for TFS User Guide 20

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 21: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

4 Configuring PreEmptive Analytics for TFSTo integrate PreEmptive Analytics with your team projects you must connect the PreEmptive Analytics forTFS Aggregator service to your Team Foundation Server instance and provision team projects for use withPreEmptive Analytics for TFS Provisioned team projects can define subscriptions to receive exception reportdata for instrumented applications and rules to define how and when to create Incident work items from theseexception reports

41 Provisioning Team ProjectsThe PreEmptive Analytics for TFS Aggregator service connects to your Team Foundation Server to create andmodify Incident work items in response to configured rules which can include criteria such as the type and quantityof exception reports received To begin using this functionality launch the Configuration Utility to connect to yourTeam Foundation Server and provision your team projects for use with PreEmptive Analytics for TFS

Verify the aggregator service installation1 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 AggregatorConfiguration service it must be corrected before you can proceed See the Troubleshooting the Aggregatortopic for steps in solving issues with the aggregator service

Connect to team project collections1 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 clickingthe Servers button

3 If the logged-in user does not have permissions to access the desired Team Foundation Server or teamproject collection click the Use Different Credentials link and supply credentials with the desiredpermissions

4 Select a team project collection and click Connect

Once you have created rules that reference this team project collection you will not be able to deleteit or change the Name or Fully Qualified URL fields without first removing all the rules that referenceit

Provision team projects for PreEmptive Analytics for TFSTeam projects must be provisioned to be used with PreEmptive Analytics for TFS In the Team Projects list eachteam project in the collection is displayed along with its provisioning status During provisioning the Incident workitem type and sample PreEmptive Analytics for TFS reports are imported into the project template The project isalso configured for use by the PreEmptive Analytics for TFS Visual Studio extension To provision a team project touse PreEmptive Analytics for TFS click the Apply link next to the desired team project Modifications made duringthe provisioning process can be rolled back by selecting the Remove link next to any provisioned team project

PreEmptive Analytics for TFS User Guide 21

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 22: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

42 Defining Exception Sets and RulesOnce you have provisioned a team project you can begin defining the rules that tell PreEmptive Analytics for TFShow to map incoming exception information to work items in those projects That mapping is defined by useof Subscriptions and Exception Sets which are configured via the PreEmptive Analytics for TFS ConfigurationUtility

Each subscription contains information about

The Company ID and Application ID of the application

The team project (in TFS) in which the work items should be created

The particular rule(s) that decide whether to create a new work item

Each rule contains settings including

The exceptions to match (via an exception set)

The type of rule (eg count the number of exception reports)

The thresholds and time limits to use when evaluating the rule

The type of work item to create (e Incident)

Each exception set contains a list of exceptions including

Name of the exception class

Whether the exception was uncaught caught andor thrown

Create exception sets1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics Configuration

Utility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the Exception Sets node in the navigation panel

3 Click the + icon to add a new empty exception set Provide a name for this exception set in the Name field

4 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 SystemNetWebException or javaioFileNotFoundException)in the Exception Type column and provide a name for this exception type (typically the unqualifiedexception type name) in the Exception Name column

PreEmptive Analytics for TFS does not attempt to traverse the inheritance hierarchy of reportedexceptions For example adding a rule for SystemApplicationException will not automaticallymatch reported exceptions that are sub-types of SystemApplicationException

5 In the Exception Category column you may choose whether this exception set should match UncaughtCaught andor Thrown exceptions Instrumented applications will send this category information along withthe exception report data in order to provide context around the situation in which the exception occurred

Incident work items contain exception information for only one exception category If an exceptionset specifies multiple exception categories then matching exception report messages will beaggregated into different Incident work items based on their exception category

6 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

Once you have created rules that reference this exception set you will not be able to delete itor change the Name field without first removing all the rules that reference it

PreEmptive Analytics for TFS User Guide 22

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 23: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Create subscriptions (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

5 Select the Subscriptions node in the left navigation and click the + icon to add a new emptysubscription

6 Provide a name for this subscription in the Name field

7 In the Identity group box supply the Company and Application ID values you used when instrumentingyour application to send exception reporting data For more information on how to add and configureexception reporting in your applications see Adding Exception Reporting to an Application

8 Leave the value of the Data Retention Days field set to the default of 30 unless you wish to change theduration for which the aggregator service will keep detailed data for each received exception

9 In the Team Foundation Server group box optionally specify the area path you wish to use for the createdwork items in the Area Path field

10 In the Rules grid you can create rules to be applied to exception reports received from the application youspecified above Please see Rule Types for details

We recommend starting with a relatively simple configuration and then adjusting that configuration as yousee exception data come in from production applications Determining the correct settings is primarily amatter of ldquotuningrdquo the rules to achieve the outcome you want and it is easiest if you start with verypermissive rules (ie that create work items for every incident)

To start this way use the default All Exceptions exception set with the ErrorCountOverTime rule type and aThreshold of 1

From there you have many options

1 Increase the threshold and adjust the time period of the default (ErrorCountOverTime) rule

2 Switch the default rule to the TopErrorsOverTime rule type and tune that rule (This is especiallyuseful if you have a high volume of exceptions)

3 Create additional exception sets that watch for specific exceptions and add additional rules to thesubscription to fine-tune how individual exception classes are processed

4 Look on the Downloads page on preemptivecom for new rule types that might be useful for you

5 Create your own custom rule to suit your particular need Please contact us to learn more

6 Any combination of the above

You can add additional subscriptions to process exception reporting data from other applications or from the sameapplication using a different Area Path by selecting the Subscriptions node and clicking the + icon to createadditional subscriptions

421 Rule TypesWhen configuring a rule in a subscription you have one or more options for different Rule Types PreEmptiveAnalytics for TFS comes with some Rule Types already installed Additional Rule Types may be available fordownload under My Account on preemptivecom or can be created to support custom behavior

PreEmptive Analytics for TFS User Guide 23

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 24: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Rule Types included with PreEmptive Analytics for TFS

ErrorCountOverTime

Create a work item when the number of exception occurrences exceeds a defined count in a given length of time

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate whether the defined count has been exceeded A workitem is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the exception occurrence count that when exceeded in the specified timeperiod triggers work item creation

InstancesPerErrorOverTime

Create a work item when the number of instances of running application sending an identical exception exceeds adefined threshold over a given length of time This rule is useful for identifying particular errors that are affecting alarge amount of users An instance is identified by the Instance ID field sent with the exception data byinstrumented client applications

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum number of instances per exception and evaluate whether the defined count has been exceeded Awork item is created when the threshold count is exceeded The default is one day (1440 minutes)

3 In the Threshold column specify the instance count that when exceeded in the specified time periodtriggers work item creation

TopErrorsOverTime

Create work items for any exceptions whose exception occurrence count is in the top N occurrence counts within adefined time length At least half the defined time length must elapse before any work items are created

1 Choose the exception set you wish to use for this rule in the Exception Set dropdown All exceptions thatare included in this set can potentially trigger the execution of the rule

2 In the Time Period (Minutes) column specify the length of time back from the current check time in whichto sum exception report occurrences and evaluate which exceptions have the top N exception counts Awork item is created for an exception when it is first evaluated as having a top N exception count Thedefault is one day (1440 minutes) Note that no work items will be created until half the time period haselapsed

3 In the Threshold column specify the number of top exceptions (Top n) within the defined time period forwhich to create work items Top refers to those exceptions having the greatest number of exceptionreport occurrences

422 Possible SurprisesThere are two aspects of the design of PreEmptive Analytics for TFS that might result in unexpected (butintentional) behavior These aspects are described in the sections below

PreEmptive Analytics for TFS User Guide 24

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 25: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Historical DataPreEmptive Analytics for TFS is designed around a ldquosubscriptionrdquo model for processing data What that means isthat in most cases new subscriptions and new rules will only process data that is received after the subscriptionor rule is created Any previously-received data will not be re-evaluated when a new subscription or rule iscreated

On the other hand once a rule is active it will cache any data that matches its settings and use that data asneeded to correctly perform its function The historical data cache is preserved as far back as the ldquoData RetentionDaysrdquo field specifies but each rule only looks as far back as its ldquoTime Periodrdquo which is usually less

Work Item UniquenessA key feature of PreEmptive Analytics for TFS is that once a work item is created for a given exception newinstances of that same exception will simply update the prior work item rather than creating a new work item This generally works as users expect but there are some scenarios that may be surprising

The key to the issue lies in defining the term ldquosame exceptionrdquo ndash ie how does PreEmptive Analytics for TFS decidewhether a new exception report matches an old one Some of the fields it uses can cause surprising side effects

Stack Trace our intuitive understanding of whether two exceptions are the ldquosamerdquo would suggest that thestack trace is a critical part of that sameness However it is possible for a single line of code to cause thesame exception type to be thrown (eg NullReferenceException) even though it was called from multiplesources Each of those sources would represent a different stack trace so PreEmptive Analytics for TFS willtreat those as different work items In most cases this is the desired behavior but there are some situationswhere it might be preferable to create a single work item for all the different stack traces PreEmptiveAnalytics for TFS has no way of identifying those cases though so it uses the more-informative option

Application Version PreEmptive Analytics for TFS does not create a new work item for each distinctversion of your application that generates the same exception Instead it creates a single work item andupdates it with counts from all versions assuming the stack traces remain identical across those versions This may be undesirable if you fix a bug and then it crops up again (with the exact same stack trace) ndash nonew work item will be created PreEmptive Analytics for TFS will however update the Version field in thework item to reflect the version reported by each new exception report

Rule ID work items are tied explicitly to the specific rule that created them That has two possibly-unexpected consequences

First if two rules both match the same exception and both meet their threshold (at the same time orin sequence) two work items will be created It will be clear from the work item titles that they camefrom two different rules but it may still be undesirable behavior Depending on the rule configurationthough the presence of multiple work items for the same exception could indicate that the exception isespecially severe

Second if a rule is deleted any work items that were created by that rule will stop being updated Recreating an exact copy of that rule will actually create new copies of each of the work items (as newexceptions come in and the thresholds are reached again) and begin updating those new work itemsfrom then forward

43 Configuring the New Data Check IntervalThe new data check interval defines the frequency of checking for new exception reports and corresponding ruleevaluation The default check interval is 60 seconds

To change the check interval you must use the PreEmptive Analytics Configuration Utility installed on the machinerunning the Aggregator Service To change the check interval

PreEmptive Analytics for TFS User Guide 25

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 26: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group

2 Select the root machine node in the navigation panel

3 Locate the Aggregator Service Check Interval edit box and enter the number of seconds to wait betweenchecks for new data The default check interval is 60 seconds

4 Save the Exception Set changes by pressing Ctrl-S or invoking the File | Save menu action

44 Configuring Custom Data Attachment LimitsWhen an application is instrumented to send custom data along with exception reports the custom data isattached to corresponding work items Limits on the quantity of custom data attached to a work item are set foreach TFS server The default attachment size is 4 megabytes of compressed data and an unlimited number of rowsthat fit within the 4 megabytes To change the custom data attachment limits use the PreEmptive AnalyticsConfiguration Utility installed on the machine running the Aggregator Service

There are three settings that control the construction of custom data attachments

Maximum Megabytes per Attachment

Maximum Rows per Attachment

Enable Compression

The total size of the attachment will not exceed the limits set for Maximum Megabytes per attachment andMaximum Rows per Attachment Selecting Enable Compression will compress the attachment contents usingstandard zip file format

To change the custom data attachment settings

1 On the machine where the Aggregator Service is installed launch the PreEmptive Analytics ConfigurationUtility from the Start menu PreEmptive Solutions PreEmptive Analytics program group These settingscannot be changed when launching the configuration utility from Visual Studio

2 Select the TFS serverproject collection in the navigation panel

3 Select the Custom Data Limits tab in the right panel

4 Locate the setting(s) you wish to change and make the modifications desired

PreEmptive Analytics for TFS User Guide 26

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 27: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

45 Making URL changes after installation451 Change Aggregator Service URL

1 Change the URLs for the aggregator configuration service by editing the configuration files located in the ldquoServicerdquofolder within the install directory You will need to update the aggregator service URLs in the both thePreEmptiveAnalyticsAggregatorAdminexeconfig and PreEmptiveAnalyticsAggregatorexeconfig configuration files

PreEmptive Analytics for TFS User Guide 27

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 28: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

2 For each edit the URL that ends with ldquoAggregatorConfigurationServicerdquo

PreEmptive Analytics for TFS User Guide 28

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 29: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

3 Restart the aggregator service which will show up as ldquoPreEmptive Analytics Aggregator Servicerdquo in the servicesconsole Also restart the PreEmptive Analytics Aggregator Administrative Console if it is running

PreEmptive Analytics for TFS User Guide 29

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 30: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

4 From within the PreEmptive Analytics Aggregator Administrative Console delete any subscriptions that depend on theTeam Foundation Server you are working with This cannot be undone so you will have to recreate any subscriptioninformation including rules

PreEmptive Analytics for TFS User Guide 30

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 31: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

5 Once yoursquove deleted the dependent subscriptions you can delete the Team Foundation Server and projectconfiguration

PreEmptive Analytics for TFS User Guide 31

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 32: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

6 Once deleted you can re-add the Team Foundation Server and project(s)

PreEmptive Analytics for TFS User Guide 32

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 33: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

7 Donrsquot forget you need to hit ldquoApplyrdquo after adding the project

8 Finally recreate any exception sets and subscriptions

PreEmptive Analytics for TFS User Guide 33

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 34: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

452 Change Fault Query Service URL1 Stop the aggregator service

2 Change the URL for the Fault Query Service by editing the aggregatorrsquos configuration file(PreEmptiveAnalyticsAggregatorexeconfig) located in the ldquoServicerdquo folder within the install directory

3 Start the aggregator service

PreEmptive Analytics for TFS User Guide 34

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 35: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

5 Adding Exception Reporting to an ApplicationApplications must be instrumented with exception reporting code in order to send exception reports to yourPreEmptive Analytics for TFS endpoint Adding exception reporting code to compiled NET applications is easyusing either PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator and Analytics a free tool included inMicrosoft Visual Studio Exception reporting can also be added to JavaAndroid applications using PreEmptiveDashO and iOS applications via the PreEmptive Analytics API

The Getting Started guide included with PreEmptive Dotfuscator Professional or PreEmptive Dotfuscator andAnalytics includes a Walkthrough section which will describe how you can easily add exception reporting code toyour NET assembly For a full description of the exception reporting instrumentation capabilities of PreEmptiveDotfuscator and Analytics please see the Exception Reporting section of the Getting Started guide The DashOUsers Guide also has a chapter on Exception Reporting

Consider allowing your customers to add additional information to Exceptions The PreEmptive Analytics API allowsfor ways to report contact information and comments when exceptions occur

Dotfuscator - use the Error Report Dialog You can also create your own ReportInfoSource

DashO - use the addUncaughtExceptionDialog annotation

PA APIs - Consult the API documentation for your platform to determine the best way to add that informationwhen reporting exceptions

When instrumenting an application for PreEmptive Analytics for TFS you do not have to use a PreEmptive-supplied CompanyKey but we recommend that you have us generate one for you so that you canguarantee that the CompanyKey is not already in use by another customer in other PreEmptive Analyticsproducts (including the Runtime Intelligence Service)

If you prefer to generate your own you can use the GUID-generator button on the Guid row under theApplicationAttribute (in Dotfuscator) and copy the value over to the BusinessAttribute You can also generateone in DashO by clicking the arrow next to the Application ID field in the Instrumentation-gtPropertiessection then copy the value for the Company ID

Please note however that once you instrument an application with a specific CompanyKey you shouldreuse that same CompanyKey for all your applications That will make it easier for you to configurePreEmptive Analytics for TFS and will make it possible for you to (later) begin using the Runtime IntelligenceService and see all your applicationsrsquo data under a single account

It is possible to instrument your applications to send non-exception data (eg platform featureperformance etc) but that data will not be processed by PreEmptive Analytics for TFS The additional datais only useful if you are using other PreEmptive Analytics products

PreEmptive Analytics for TFS User Guide 35

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 36: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

6 Examining Incidents in Team ExplorerPreEmptive Analytics for TFS exception reporting includes a special work item type named Incident to containinformation about exceptions that match the rules defined for the PreEmptive Analytics for TFS Aggregator serviceIt also includes a Team Explorer pane that allows you to view Incident items and reports and configure theaggregator service rules

If you are not seeing incidents in TFS please check that

Visual Studio or Team Explorer is installed

The PreEmptive Analytics for TFS Endpoint service is deployed

A TFS project is provisioned for PreEmptive Analytics for TFS via the PreEmptive Analytics ConfigurationUtility

Exception report messages are being sent from an application instrumented with exception reporting

The PreEmptive Analytics for TFS Aggregator service is deployed and rules are defined for the instrumentedapplication

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

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

The Title field is automatically populated with the name of the rule that caused the incident to be createdthe 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 wereconfigured 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 Innerexceptions 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 theInstance ID column will contain the identifier of the application instance that experienced theexception

If configured during instrumentation and if provided by the user that experienced the exception theContact and Comment columns may contain user-supplied contact information and user-suppliedcomments 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 theapplication at the time the exception occurred

PreEmptive Analytics for TFS User Guide 36

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 37: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

In the Metrics section the number of individual exception reports received that matched the rule is shown inthe Raw Exception Count field

The Exception Category field shows the category of exception (uncaught caught or thrown) that thisIncident work item is tracking

If the application was configured to send unique instance identifiers during instrumentation the ExceptionCount By Instance field will show the number of different instances of the application (as defined by uniqueserial 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 isenabled as new exceptions are received that continue to match the rule the aggregated counts in the workitem will be updated and additional detail data will be added to the Incident Details view If you switch thissetting to No no further updates to the work item or incident details will be made and any exceptionmessages that continue to match the rule will be ignored You can switch this setting back to Yes at anytime to resume updating the work item and incident details Any past exception reports (up to the configuredData Retention Days setting) that were received during the time the Accept New Data value was set to Nowill be immediately processed and added to the work item

When Custom Data is sent with the Exception report the custom data will appear as a zip file attachment tothe work item

PreEmptive Analytics for TFS User Guide 37

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 38: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

7 Upgrading PreEmptive Analytics for TFSUpgrading PreEmptive Analytics for TFS can generally be performed by simply running the installer for the newversion on the same machine(s) where the prior versions components are installed We recommend backing upthe machine before performing the upgrade The installer will upgrade whichever components are on the machinepreserving settings and data

If you wish to change the components installed on each machine during the upgrade process you will need touninstall all the prior versions components and then perform a clean install of the new version The uninstaller willleave the data in place so if you configure the new version to use the same database as the prior version yourdata will be migrated into the new version

71 Validating the UpgradePlease take the following steps to ensure that the installation is working properly after the upgrade

Endpoint

1 Use an instrumented application to ensure that the endpoint is still receiving messages

a The endpoint URL is unchanged by the upgrade

b Use Fiddler or another network debugging tool to monitor incoming messages and see that a 202response is sent

2 If any manual changes were made to the Endpoint authentication in IIS please ensure that those are stillthere

a If ldquoAnonymous Authenticationrdquo was manually disabled for the ldquoanalyticsrdquo application in IIS you willneed to disable it again

Database

1 Query the ldquoProductVersionrdquo table to confirm the version is updated to the latest version

2 Query the ldquoFaultsrdquo table to confirm that new messages are appearing in the database

Aggregator

1 Open the Aggregator administration console and review your configured exception sets and subscriptions

a When upgrading from CE consider updating the AllExceptions exception set to include Caught andThrown exceptions in addition to Uncaught

2 Check that work items are being createdupdated correctly in TFS after the expected time interval

3 InstallUpgrade the Web Components

PreEmptive Analytics for TFS User Guide 38

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 39: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

8 Troubleshooting

Starting Point Open the Windows Event ViewerDepending 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 eventvwrmsc and press the Enter key

Windows XP or Windows Server

1 Click Start gt Run

2 In the dialog type eventvwrmsc in the text box

3 Click OK

Enable Debug LoggingWhen troubleshooting issues it may be necessary to enable debug logging

Endpoint and Query Service

1 Open the IIS management console

2 Expand the PreEmptive Analytics Endpoint site (Note The site name may have been changed duringinstallation)

3 Choose one of the following depending on where you wish to enable debug loggingPreEmptive Analytics Endpoint - Both services

analytics - The Query Service

message - The Endpoint Service

4 Select Application Settings

5 Add a setting EnableDebugLogging with a value of true

6 Restart the site

PreEmptive Analytics for TFS User Guide 39

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 40: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Aggregator

1 Stop the aggregator service or close the configuration utility depending on where you wish to enable debuglogging

2 Backup and edit one of the following files based on where you wish to enabled debug logging (Files arelocated here by default CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics forTFSService)

PreEmptiveAnalyticsAggregatorexeconfig - Aggregator Service

PreEmptiveAnalyticsAggregatorAdminexeconfig - Configuration Utility

3 Find the EnableDebugLogging setting and change the value to True

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

ltsetting name=EnableDebugLogging serializeAs=Stringgt

ltvaluegtTrueltvaluegt

ltsettinggt

ltPreEmptiveAnalyticsAggregatorCommonPropertiesSettingsgt

4 Start the aggregator service or open the configuration utility

Viewing the PreEmptive Event Log1 In the tree view to the left expand Applications and Services Logs

2 Click PreEmptive

Troubleshooting ConceptsTroubleshooting Installation

Use this section to troubleshoot issues installing PreEmptive Analytics for TFS

Troubleshooting the Endpoint

Use this section to troubleshoot issues receiving persisting or retrieving exception message data using thePreEmptive Analytics for TFS Endpoint Services

Troubleshooting the Aggregator

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

PreEmptive Analytics for TFS User Guide 40

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 41: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

81 Troubleshooting InstallationThis section provides troubleshooting information related to installing PreEmptive Analytics for TFS

These steps will help solve most problems

1 If an error message is provided follow any instructions it lists

2 Double check you meet the Prerequisites listedMake sure you ran the installer with administrative rights

Verify the user accounts you provided the install wizard have the required permissions

Check that the ports you specified are available

3 Run the installer with installer logging turned on

a Go to httpsupportmicrosoftcomkb223300

b Follow the instructions

4 Check the Event Log for any error messages

Specific Cases

Problem Potential Cause Solution

Installer appeared to stop atPublishing Product Information

The Application Pool Identityprovided was set to use NETWORKSERVICE and Integrated Securitywas selected

The provided user did not have therequired permissions for both IISand SQL

Use the default LOCAL SERVICE or auser with the necessary permissions

If you are still experiencing issues installing contact PreEmptive Support

82 Troubleshooting the Endpoint

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

PreEmptive Analytics for TFS User Guide 41

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 42: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Issues involving the endpoint message service

Error Solution

HTTP Error 503 (The service isunavailable)

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 Analyticsendpoint services (Team Foundation Server by default)

5 Right-click message gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version drop downchoose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user message

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The message usershould belong to the pa_message role

HTTP Error 4011 (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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Click message

6 Double-click Authentication

7 Select Anonymous Authentication and then click Enable in theActions pane

PreEmptive Analytics for TFS User Guide 42

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 43: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Issues involving the endpoint query service

Error Solution

HTTP Error 503 (The service isunavailable)

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 AnalyticsEndpoint services (Team Foundation Server by default)

5 Right-click analytics gt Manage Application gt AdvancedSettings

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 v40 right-click and chooseBasic Settings From the NET Framework version dropdown choose the current version of the NET Framework v40

12 If the Identity is not set to the account name you chose duringinstallation right-click and choose Advanced Settings In theIdentity field click the button and choose the correct accountname You may be asked to provide the password for the account

13 Click OK

SystemDataSqlClientSqlException(0x80131904) Cannot opendatabase Exceptions requested bythe login The login failed

Login failed for user data

1 Using SQL Server Management Studio make sure you can connectto your PreEmptive Analytics Exceptions database using theaccount name and password you specified during installation

2 Open a new connection to your PreEmptive Analytics Exceptionsdatabase using an administrator account The data user shouldbelong to the pa_data role

HTTP Error 4011 (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 Analyticsendpoint services (Team Foundation Server by default)

5 Click analytics

6 Double-click Authentication

PreEmptive Analytics for TFS User Guide 43

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 44: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

7 Choose how you wish to authenticate requests to your raw dataservice

If you wish to allow anonymous access to your raw dataservice select Anonymous Authentication and then clickEnable in the Actions pane OR

If you wish to protect access to your raw data service selectBasic Authentication and then click Enable in the Actionspane When using Basic authentication you should serve yourendpoint raw data service over SSL only as credentials willbe transmitted in plain text

HTTP Error 4043 or 40417 (NotFound)

1 When running desktop versions of Windows

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Expand NET Framework 45 Advanced Services

c Expand WCF Services

d Make sure HTTP Activation is checked

2 When running Windows Server

a Go to Control Panel-gtPrograms-gtTurn Windowsfeatures on or off

b Select your server in the Add Roles and Features Wizard

c Select the Features section

d Expand NET Framework 45 Features

e Expand WCF Services

f Make sure HTTP Activation is checked

Issue after enabling WCF HTTP Activation

Error Solution

Could Not Load TypeSystemServiceModelActivationHttpModule

Due to a known issue with NET Framework enabling WCF HTTPActivation might cause an issue with existing HTTP services(including TFS) This error can occur when IIS is installed afterinstalling NET Framework 4 or if the 30 version of the WCFHttp Activation module is installed after installing IIS and NETFramework 4

To resolve the problem you must use the ASPNET IISRegistration Tool (Aspnet_regiisexe) to register the correctversion of ASPNET This can be accomplished by using the -iruparameters when running aspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studiocommand prompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

PreEmptive Analytics for TFS User Guide 44

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 45: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

83 Troubleshooting the AggregatorThis section provides troubleshooting information related to the PreEmptive Analytics for TFS Aggregator service This service isresponsible for sending requests to the Query Service to get recent exception data managing criteria (rules) for exception types andconnecting to TFS to create work items

Configuration Troubleshooting

The PreEmptive Analytics Configuration Utility is automatically launched after installation Here are solutions for common problems

Problem Potential Cause Solution

Add Subscription isdisabled

It is not connected to a TFS Server Connect to a TFS Server choose a Team Project and clickApply

See the Provisioning Team Projects section

A Team Project has not beenprovisioned

Select a TFS Server choose a Team Project and click Apply

See the Provisioning Team Projects section

Runtime TroubleshootingIssues experienced by the aggregator service are logged in the Windows Event Log in the PreEmptive node of the Applications andServices Logs section Examining this log can often provide assistance in resolving aggregator service issues

Problem PotentialCause

Solution

Work Items are not showing up as expected Raw dataservice endpointis not running

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis not accessiblefrom themachine hostingthe aggregatorservice

1 Attempt to ping the server hosting the Raw Data service fromthe machine hosting the Aggregator service

2 Check firewall settings on both machines

3 Ensure you are able to browse to the raw data service endpointURL (If you used the default values during installation thisshould follow the form httpltendpoint services machinenamegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

Raw dataservice isexperiencing anerror

See the Troubleshooting the Endpoint topic

Raw dataservice endpointis using basicauthenticationand credentialsin theaggregatorservice configfile are missingor incorrect

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltappSettingsgt element and specify the user nameand password used to access the endpoint raw data service inthe EndpointUserName and EndpointPassword values

PreEmptive Analytics for TFS User Guide 45

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 46: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Raw dataservice endpointis using basicauthenticationand login namein theaggregatorservice configfile is not anauthorized userin 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 thePreEmptiveAnalyticsAggregatorexeconfig file is listed(or is a member of a listed group)

Raw dataservice endpointis using basicauthenticationaggregatorservice isconfigured toconnect usinghttp URI scheme(not https)

Using basic authentication over SSL is highly recommended ascredentials are transmitted in plain text However if your configurationrequires the PreEmptive Analytics endpoint raw data service to usebasic authentication over unsecured HTTP instead of SSL you willneed to locate the ltbindinggt element named BasicSecurity andchange its security mode value from Transport toTransportCredentialOnly

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics AggregatorService entry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

Rule criteria notbeing met

Using SQL Server Management Studio connect to the exceptionsdatabase being used to persist exception data Query against theExceptions table and verify the number of exception reportmessages exceeds the threshold and have been persisted within thetime span specified in the rule

Exceptionsreceived not inrulersquos exceptionset

Inspect the exception set assigned to the rule and ensure theexceptions being received are included or create a new exception setthat includes the exceptions being received and assign it to the rule

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

TFS Work itemquery does not

Ensure that the Incident work item type is included in the TFS workitem query you wish to use for viewing work items created by the

PreEmptive Analytics for TFS User Guide 46

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 47: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

include Incidentwork items

Aggregator service

PreEmptive Analytics node is not visible inTeam Explorer

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects section of the Provisioning TeamProjects topic

Visual Studioextension is notinstalled on localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Exception or Incident Details tab is notvisible in the Incident work item

VisualStudio extensionis not installedon localmachine

See the Install the Visual Studio extension section of the DefiningException Sets and Rules topic

Configuration Utility or VS extension canrsquotconnect to configuration service

Aggregatorservice is notrunning

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Run

Aggregatorservicecredentials areincorrect

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK

6 If you changed the service account you must also grant itpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Aggregatorservice accountdoes nothave Log on asa Servicerights

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator entry andchoose Properties

3 Select the Log On tab

4 Verify the User ID and re-enter the password of the serviceaccount you wish to use If the account is a local accountspecify the full account name (eg COMPUTERTfsServicerather than simply TfsService or TfsService)

5 Click OK If permissions to log on as a service were notpreviously assigned to that account you will be notified andthey will be granted automatically

PreEmptive Analytics for TFS User Guide 47

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 48: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Aggregatorservice accountdoes not havepermission tohostconfigurationservice on port80

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with the phrase HTTP could notregister URL http+80AggregatorConfigurationServiceYour process does not have access rights to this namespaceor The HTTP service located athttphostAggregatorConfigurationServiceGetConfiguration isunavailable

5 If such an entry exists you must grant the service accountpermissions to host the configuration service on port 80

a Launch an elevated command prompt and execute thecommand netsh http del urlaclurl=http+80AggregatorConfigurationServiceto remove permissions from any other accounts Ifrunning this command returns an error it simply meansthat no other accounts had been granted permissions tohost the service and you should proceed to the nextstep

b Execute the command netsh http add urlaclurl=http+80AggregatorConfigurationServiceuser=ltService Account User Namegt to grantpermissions for the new service account to host theaggregator configuration service

Note You may also need to grant permissions to the program datadirectory as mentioned below

Aggregatorservice accountdoes not havepermission tothe programdata directory

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like Access to thepath ProgramDataPreEmptive SolutionsPreEmptiveAnalyticsis denied

5 If such an entry exists you must grant the service account fullpermissions to ProgramDataPreEmptiveSolutionsPreEmptive Analytics and its sub folders

Aggregatorservice accountdoes not havepermissions toaccess the TFScollection

1 Click Start

2 In the Search Programs and files textbox type eventvwrmsc

3 Under Applications and Services Logs select the PreEmptivenode

4 Look for an error log entry with a phrase like TF30063 Youare not authorized to access httphostporttfs

5 If such an entry exists you must grant the service account TFSpermissions

Aggregatorconfigurationservice is beingblocked by afirewall

Launch the configuration tool for your firewall Allow thePreEmptiveAnalyticsAggregatorexe application to acceptincoming connections on port 80 ThePreEmptiveAnalyticsAggregatorexe application is located in theService subfolder within the PreEmptive Analytics installation directory(by default CProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics )

PreEmptive Analytics for TFS User Guide 48

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 49: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Aggregatorservice raw dataconnection isconfiguredincorrectly orraw data serviceis inaccessible

1 Open the PreEmptiveAnalyticsAggregatorexeconfig filefrom within the Service subdirectory of the PreEmptiveAnalytics aggregator service install directory (by defaultCProgram Files (x86)PreEmptive SolutionsPreEmptiveAnalytics ) using a text editor

2 Locate the ltendpointgt element and verify that the value ofthe address attribute is a valid exception endpoint queryservice URL

If this is configured correctly

1 Attempt to ping the server hosting the raw data serviceendpoint 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 serviceendpoint URL (If you used the default values during installationthis should follow the form httpltendpoint servicesmachine namegt8000analyticsFaultQuerysvc)

4 If you are able to browse to the endpoint URL but see an HTTPerror code reference the Troubleshooting the Endpoint topicwith any HTTP Error code displayed

(For VSextension)Aggregatorservice is notaccessible fromthe machinerunning VisualStudio

1 Attempt to ping the server hosting the Aggregator service fromthe machine running Visual Studio

2 Check firewall settings on both machines

3 Ensure you are able to browse to the aggregator configurationservice URL (This should follow the formhttpltaggregator service machinenamegtAggregatorConfigurationService)

Provisioning a team project fails Aggregatorservice is notrunning underan account withpermissions tocreate and editwork items inTeamFoundationServer

The Analytics aggregator service must be configured to execute usingan account with permissions to create and edit work items in TeamFoundation Server

1 Launch the Control Panel and open the AdministrativeTools folder Double-click the Services icon

2 Right-click the PreEmptive Analytics Aggregator Serviceentry and choose Properties

3 Select the Log On tab

4 Specify the User ID and password of the current TFS ServiceAccount If the account is a local account specify the fullaccount name (eg COMPUTERTfsService rather than simplyTfsService or TfsService)

5 Click OK

To determine the name of an account with permissions to create andedit work items in Team Foundation Server launch the TeamFoundation Server Administration Console and click on theApplication Tier node Click on Group Membership and locate anaccount that is a member of a group with permissions to create andedit work items such as the Team Foundation Administrators group

PreEmptive Analytics hub is not visible inVisual Studio

Team project isnot provisionedfor PreEmptiveAnalytics

See the Provision team projects for PreEmptive Analytics sectionof the Provisioning Team Projects topic

Visual Studioextension cachemust berefreshed

Launch an instance of the Visual Studio Command Prompt and executethe command devenvexe setup to refresh the extension cache

PreEmptive Analytics for TFS User Guide 49

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 50: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Sample reports are not working correctly TFS datawarehouse hasnot run

The TFS data warehouse process executes every two hours by defaultYou can wait for the process to occur or manually execute the datawarehouse process by following the instructions in the ManuallyProcess the Data Warehouse and Analysis Services Cube for TeamFoundation Server topic of the Team Foundation Serverdocumentation

Report data iscached

1 Launch Internet Explorer and browse to your TFS reports site(typically httpltYour TFS ServergtReports)

2 Click on the TfsReports folder to open it then open your teamproject collection folder your team project folder and finallythe PreEmptive Analytics folder

3 Hover over the report in question and click to open thedropdown menu Click Manage

4 Click Processing Options in the left navigation

5 Select the Always run this report with the most recentdata radio button and underneath it select Do not cachetemporary copies of this report

6 Click Apply at the bottom of the page

In TFS Web Access the Incident work itemdoes not show the exception information oran error is displayed

PreEmptiveAnalytics WebComponents aredisabled or notinstalled

Follow the installation process in the Installing the Web Componentstopic Ensure you enable the extension after it is installed

Cannot connect to TFS due to followingerrorSystemServiceModelActivationHttpModule

This might also cause a 400 Bad Requesterror in Aggregator admin console whentrying to connect to the broken TFSinstance

Due to a knownissue with NETFrameworkenabling WCFHTTP Activationmight cause anissue withexisting HTTPservices(including TFS)

This error canoccur when IISis installed afterinstalling NETFramework 4 orif the 30version of theWCF HttpActivationmodule isinstalled afterinstalling IISand NETFramework 4

To resolve the problem you must use the ASPNET IIS RegistrationTool (Aspnet_regiisexe) to register the correct version of ASPNETThis can be accomplished by using the -iru parameters when runningaspnet_regiisexe as follows

aspnet_regiisexe -iru

You would either have to run this command in Visual Studio commandprompt or download the ASPNET IIS Registration Tool(Aspnet_regiisexe)

Viewing the Aggregator Service Debug ConsoleOccasionally a problem with the PreEmptive analytics aggregator service may present itself without writing a meaningful event to theWindows event log In these cases it can be useful to view the debug output of the aggregator service itself using the aggregator servicedebug console Running the service in debug mode should only be done to debug specific issues - once the issues are solved do notcontinue to run the service in debug mode Instead exit the debug console and start the PreEmptive Analytics Aggregator Service fromthe Services console directly

1 Ensure the PreEmptive Analytics Aggregator Service is stopped from within the Services console

PreEmptive Analytics for TFS User Guide 50

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 51: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

2 From the command prompt change directory to the Service subfolder within the PreEmptive Analytics installation directory (bydefault CProgram Files (x86)PreEmptive SolutionsPreEmptive Analytics)

3 Execute the command PreEmptiveAnalyticsAggregatorexe 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 theServices console

PreEmptive Analytics for TFS User Guide 51

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 52: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

9 MonitoringSo far we have only seen a need for uptime monitoring of the PA for TFS components The monitoring werecommend is basic service state monitoring for the endpoint in IIS (ldquoPreEmptive Analytics Endpointrdquo) and theaggregator Windows service (ldquoPreEmptive Analytics Aggregator Servicerdquo)

You could also monitor the endpoint by periodically sending a GET to the message and FaultQuery services in IIS

For the message service you should get a 405 error when you hit http[s][hostname][port]messageEndpointashxEven though this is an error it demonstrates that the endpoint is functioning

For the FaultQuery service you should get a 200 when you hit http[s][hostname][port]analyticsFaultQuerysvc

PreEmptive Analytics for TFS User Guide 52

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 53: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

10 MaintenanceThere is not much maintenance necessary for PreEmptiveAnalytics for TFS However if your machine is gettinglow on space you can manually remove exceptions from the endpoint database using the PurgeData storedprocedure These entries are no longer needed once the data has been aggregated (unless you will have a need tore-aggregate)

PurgeData

This stored procedure will clear the data from the various tables in the PA_Exceptions database based on a daterange of when exceptions were encountered When you run this procedure you will need to supply two values

startdate - The earliest datetime to delete

enddate - The latest datetime to delete (Optional - if not provided the current time is used)

Both values are inclusive Be careful when specifying dates without times (EG The range 112013 to12312013 will not include exceptions which occured on 12312013 because it will be interpreted as12312013 000000 If you want to include all the entries on a particular day use the time 235959997 in theenddate)

PreEmptive Analytics for TFS User Guide 53

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 54: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

11 IndexAdding Exception Reporting to an Application 35

Change Aggregator Service URL 27-33

Change Fault Query Service URL 34

Configuring Custom Data Attachment Limits 26

Configuring PreEmptive Analytics for TFS 21

Configuring the New Data Check Interval 25-26

Custom Data 36-37

Defining Exception Sets and Rules 22-23

ErrorCountOverTime 22-23

Examining Incidents in Team Explorer 36-37

Exception Sets 22-23

Installing PreEmptive Analytics for TFS 6

Installing the Aggregator 13-14

Installing the Endpoint and Aggregator Together 14-16

Installing the Endpoint 12-13

Installing the Visual Studio Components 19

Installing the Web Components 19-20

Maintenance 53

Monitoring 52

Overview 5

Performing a Basic (single-machine) Installation 11-12

Performing an Advanced Installation 12

Planning a Production Installation 7-10

Possible Surprises 24-25

Prerequisites 6-7

PreEmptive Analytics for TFS User Guide 54

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index
Page 55: PreEmptive Analytics for TFS User Guide · PreEmptive Analytics for TFS User Guide 3 ... An installed and operating PreEmptive Analytics for TFS Endpoint and Aggregator Visual Studio

Provisioning Team Projects 21

Rule Types 23-24

Rules 22-23

Securing the Components 16-19

Subscriptions 22-23

TopErrorsOverTime 22-23

Troubleshooting Installation 41

Troubleshooting the Aggregator 45-51

Troubleshooting the Endpoint 41-44

Troubleshooting 39-40

Upgrading PreEmptive Analytics for TFS 38

Validating the Upgrade 38

PreEmptive Analytics for TFS User Guide 55

copy 2015 PreEmptive Solutions LLC All Rights Reserved

wwwpreemptivecom

  • Table of Contents
  • Overview
  • Installing PreEmptive Analytics for TFS
    • Prerequisites
    • Planning a Production Installation
    • Performing a Basic (single-machine) Installation
    • Performing an Advanced Installation
      • Installing the Endpoint
      • Installing the Aggregator
      • Installing the Endpoint and Aggregator Together
      • Securing the Components
        • Installing the Visual Studio Components
        • Installing the Web Components
          • Configuring PreEmptive Analytics for TFS
            • Provisioning Team Projects
            • Defining Exception Sets and Rules
              • Rule Types
              • Possible Surprises
                • Configuring the New Data Check Interval
                • Configuring Custom Data Attachment Limits
                • Making URL changes after installation
                  • Change Aggregator Service URL
                  • Change Fault Query Service URL
                      • Adding Exception Reporting to an Application
                      • Examining Incidents in Team Explorer
                      • Upgrading PreEmptive Analytics for TFS
                        • Validating the Upgrade
                          • Troubleshooting
                            • Troubleshooting Installation
                            • Troubleshooting the Endpoint
                            • Troubleshooting the Aggregator
                              • Monitoring
                              • Maintenance
                              • Index