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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
Top Related