PreEmptive Analytics Data Hub User Guide

OVERVIEW

Installation

Configuration

Management

Monitoring

Troubleshooting

Advanced Configuration

LICENSE

Deployment

Once a suitable host is selected for the Data Hub, follow the relevant sections below to install the software and begin accepting messages.

Standard Installation

To install the Data Hub software:

  1. Copy the provided installer to your server.
  2. As a user with local administrator rights to the machine, run the installer.
  3. Follow the prompts in the installer.
    • On most screens the default choices are probably acceptable; any changes should be based on your internal hosting and network policies.
    • When asked to choose a location for the RabbitMQ data folder, you may wish to choose a different location for performance reasons.
  4. When ready to install, click Install.
  5. When the installation has finished, record the provided Endpoint URL for use when instrumenting your applications.
    • Note that the URL provided will use the machine name as the hostname. If the Data Hub is to receive messages through another domain name, use that name instead.
  6. Optionally configure logging and/or configure Windows Event Log retention settings.
  7. Optionally (but recommended) configure SSL.
  8. Check the Windows Event Log for any errors or warnings.

Assuming there are no errors, you should now be able to configure appropriate destinations and begin sending data to the Data Hub using the Endpoint URL provided.

Inserting a Data Hub in Front of PreEmptive Analytics for TFS

If you already have a PreEmptive Analytics for TFS (PA TFS) endpoint deployed and receiving data, you may wish to insert the Data Hub in front of that endpoint. Doing so will redirect all messages originally intended for PA TFS to the Data Hub, allowing you to gain the advantages of the Data Hub without needing to re-instrument previous applications.

It is possible to install the Data Hub on a separate host and use DNS or load balancing to redirect the traffic, or to install the Data Hub on the same host as PA TFS. We recommend installing it on a separate host, when possible, but either configuration is supported.

Note that these instructions assume that the PA TFS endpoint uses the default port, 8000, and that SSL was not used. Adjust appropriately depending on your installation to ensure all ports and schemes are supported.

Deploying on a Different Host than PA TFS Endpoint

This section explains how to deploy the Data Hub on a new host, redirect all traffic intended for the PA TFS endpoint to the Data Hub, and finally dispatch messages from the Data Hub to the PA TFS endpoint.

These steps assume the following prior state:

  • There are three hosts:
    • The Data Hub host, where the Data Hub will be deployed.
    • The PA TFS endpoint host.
    • The PA TFS aggregator host (note that, in fact, this may be the same as the PA TFS endpoint host, but these instructions assume it is separate).
  • The Data Hub host has no existing IIS Web Site bindings on port 8000.
  • The PA TFS endpoint host has both public and internal hostnames.
    • The public hostname, PATFS_PUBLIC, was used to instrument all applications that send data to the PA TFS endpoint.
    • The internal hostname, PATFS_INTERNAL can be used to access the PA TFS endpoint host from both of the other hosts.
  • The PA TFS endpoint host has the PA TFS endpoint and fault query services bound to port 8000, the default.
    • Endpoint service URL: http://PATFS_PUBLIC:8000/message/endpoint.ashx
    • Fault Query service URL: http://PATFS_PUBLIC:8000/analytics/FaultQuery.svc
  • The PA TFS aggregator host refers to the endpoint host's Fault Query service using the PATFS_PUBLIC hostname.

The final state will be:

  • The PATFS_PUBLIC hostname now points to the IP of the Data Hub host. PATFS_INTERNAL still refers to the PA TFS endpoint host.
  • The Data Hub host has the Data Hub endpoint bound to ports 80 and 8000, with a rewrite rule redirecting :8000/message/endpoint.ashx to :8000/endpoint.
    • Data Hub URL (for newly-instrumented applications): http://PATFS_PUBLIC/endpoint
    • Data Hub URL (for previously-instrumented applications): http://PATFS_PUBLIC:8000/message/endpoint.ashx
  • The PA TFS endpoint host's bindings and configuration are unchanged, but now must be referred to by the internal hostname.
    • Endpoint service URL: http://PATFS_INTERNAL:8000/message/endpoint.ashx
    • Fault Query service URL: http://PATFS_INTERNAL:8000/analytics/FaultQuery.svc
  • The PA TFS aggregator host refers to the endpoint host's Fault Query service using the PATFS_INTERNAL hostname.

To deploy the Data Hub in front of PA TFS, on a new host:

  1. On the PA TFS aggregator host, modify the Fault Query service URL to use the endpoint host's internal hostname.
  2. On the Data Hub host, install the Data Hub using the default settings.
  3. On the Data Hub host, add a binding on the PreEmptive Analytics Data Hub Web Site to port 8000.
    • This port must also be permitted through your firewall, just as it was for the PA TFS endpoint host.
  4. On the Data Hub host, configure the site-specific rewrite rule (see below):
    • For the Match URL pattern, use ^message/endpoint\.ashx$.
    • For the Server Port pattern, use ^8000$.
    • For the Rewrite URL, use endpoint.
  5. On the Data Hub host, add a destination with the URL http://PATFS_INTERNAL:8000/message/endpoint.ashx.
  6. Configure the hostnames such that PATFS_PUBLIC points to the Data Hub, not the PA TFS endpoint.

Modifying the Fault Query Service URL

PA TFS has two separate server components: the endpoint, and the aggregator (though the basic installation will place both components on the same host). The aggregator service on the aggregator host must know the URL of the endpoint host in order to query it for faults that have been received. As deploying the Data Hub in front of PA TFS requires changing the public hostname of the PA TFS endpoint to instead point to the Data Hub, this URL held by the aggregator must be updated to use the internal hostname.

To change the URL the aggregator service uses to connect to the endpoint host, on the aggregator host:

  1. Stop the aggregator service.
  2. Edit the [PA TFS application folder]\Service\PreEmptive.Analytics.Aggregator.exe.config file.
    • In Pro, the default application folder location is: C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics for TFS.
    • In the Community Edition, the default application folder location is: C:\Program Files (x86)\PreEmptive Solutions\PreEmptive Analytics for TFS CE.
  3. In the <system.serviceModel> section, under <client>, locate the <endpoint> element.
  4. Alter the address attribute to use the internal hostname (PATFS_INTERNAL in the example), keeping the rest of the URL the same.
    • If the PA TFS endpoint and aggregator are both on the same host, you may instead use localhost.
  5. Save the file.
  6. Start the aggregator service.

Adding an IIS Binding

Deploying the Data Hub in front of PA TFS will require adding an additional binding (port association) to one of the IIS Web Sites:

  • If the Data Hub and PA TFS share a host, the PA TFS endpoint Web Site (PreEmptive Analytics Endpoint) must have a private port (8005) bound, so that the Data Hub can dispatch to PA TFS without using the primary port (8000), as this port will be configured to redirect back to the Data Hub.
  • If the Data Hub is on a different host, the Data Hub Web Site (PreEmptive Analytics Data Hub) must have a second public port bound to match the PA TFS public port (8000).

To add a binding to a Web Site:

  1. If the port will use SSL, import the certificate into IIS.
  2. Open the IIS Manager (inetmgr.exe).
  3. Under the server node, select the Web Site in question.
  4. Choose Bindings... from the Actions pane.
  5. Click Add....
  6. If using SSL, choose the https from the Type drop-down. Otherwise, choose http.
  7. Enter the port to add.
  8. If using SSL, choose the imported certificate in the SSL certificate drop-down.
  9. Select OK.
  10. Select Close, then close the IIS Manager.

Adding the Rewrite Rule (on a Data Hub host)

If the Data Hub is on a different host than the PA TFS endpoint, the Data Hub Web Site (PreEmptive Analytics Data Hub) must have a rewrite rule to redirect requests from the PA TFS endpoint's path (e.g., /message/endpoint.ashx) to the Data Hub endpoint's path (/endpoint).

To add such a rewrite rule:

  1. Install the IIS URL Rewrite extension.
  2. Open the IIS Manager (inetmgr.exe).
  3. Under the server node, select the PreEmptive Analytics Data Hub Web Site.
  4. Select URL Rewrite.
  5. Choose Add Rule(s)... in the Actions pane.
  6. Choose a blank inbound rule.
  7. Fill the Name field as desired.
  8. In the Match URL section, fill the Pattern field with the a regular expression to match the old endpoint's path (^message/endpoint\.ashx$ in the example).
  9. In the Conditions section, click Add....
  10. In the Condition input field, enter {SERVER_PORT}.
  11. Fill the Pattern field with a regular expression to match the old endpoint's port (^8000$ in the example).
  12. Click OK.
  13. In the Action section, fill the Rewrite URL field with the Data Hub endpoint's path, without the leading / (endpoint in the example).
  14. Choose Apply... from the Actions pane.
  15. Close the IIS Manager.

Configuring Hostnames

If the PA TFS endpoint and the Data Hub are located on different hosts, the PA TFS endpoint's public hostname must now redirect to the Data Hub, in order for applications instrumented to the old endpoint to send their messages to the Data Hub.

The process of actually pointing the old hostname to the new hostname varies depending on the way the network is managed. Usually, this involves reconfiguring a Domain Name Server or load balancer.

For example, let's assume we have installed the Data Hub on datahub.example.com, and our applications are instrumented to send messages to the PA TFS endpoint at analytics.example.com, and a Domain Name Server set up as follows:

Hostname IP TTL (sec)
analytics.example.com 0.1.2.3 86400
datahub.example.com 4.5.6.7 86400

By modifying the analytics.example.com entry to now point to the Data Hub's IP, 4.5.6.7, requests made to analytics.example.com will now be equivalent to those going to datahub.example.com. However, not all clients will do so immediately. Some clients may still have the old IP cached, so the changeover won't be complete until the TTL has expired. Thus, the original endpoint (located at 0.1.2.3) may continue to receive data directly from instrumented applications for at least one day (86400 seconds) in this scenario.

Deploying on the Same Host as PA TFS Endpoint

This section explains how to deploy the Data Hub on a the PA TFS endpoint host, redirect all traffic intended for the PA TFS endpoint to the Data Hub, and finally dispatch messages from the Data Hub to the PA TFS endpoint.

These steps assume the following prior state:

  • There are two hosts:
    • The shared host, which hosts the PA TFS endpoint services, and where the Data Hub will be deployed.
    • The PA TFS aggregator host (note that, in fact, this may be the same as the shared host, but these instructions assume it is separate).
  • The shared host has the PA TFS endpoint and fault query services bound to port 8000, the default.
    • Endpoint service URL: http://SHARED_HOST:8000/message/endpoint.ashx
    • Fault Query service URL: http://SHARED_HOST:8000/analytics/FaultQuery.svc

The final state will be:

  • The shared host has the Data Hub bound to port 80 and the PA TFS endpoint bound to ports 8000 and 8005, with a rewrite rule redirecting :8000/message/endpoint.ashx to :80/endpoint.
    • Data Hub URL (for newly-instrumented applications): http://SHARED_HOST/endpoint
    • Data Hub URL (for previously-instrumented applications): http://SHARED_HOST:8000/message/endpoint.ashx
    • PA TFS Endpoint service URL: http://SHARED_HOST:8005/message/endpoint.ashx
    • PA TFS Fault Query service URLs: http://SHARED_HOST:8000/analytics/FaultQuery.svc and/or http://SHARED_HOST:8005/analytics/FaultQuery.svc

To deploy the Data Hub in front of PA TFS, on the same host as the PA TFS endpoint:

  1. Install the Data Hub using the default settings.
  2. Add a binding on the PreEmptive Analytics Endpoint Web Site (the PA TFS endpoint) to port 8005.
    • It is not recommended that this port be enabled in your firewall; all access to it should be made from the local host.
  3. Add a destination to the Data Hub with the URL http://localhost:8005/message/endpoint.ashx.
  4. Configure the proxy and server-wide rewrite rule:
    • For the Match URL pattern, use ^message/endpoint\.ashx$.
    • For the Server Port pattern, use ^8000$.
    • For the Rewrite URL, use http://localhost/endpoint.

Adding the Rewrite Rule (on a shared host)

If the Data Hub and PA TFS share a host, the server must have an internal proxy and a rewrite rule to redirect requests from the PA TFS endpoint's port and path (e.g., :8000/message/endpoint.ashx) to the Data Hub endpoint's port and path (e.g., :80/endpoint).

To activate the proxy and add such a rewrite rule:

  1. Install IIS Application Request Routing (which also includes the URL Rewrite extension).
  2. Open the IIS Manager (inetmgr.exe).
  3. Select the server node.
  4. Select Application Request Routing Cache.
  5. Choose Server Proxy Settings... in the Actions pane.
  6. Check the Enable Proxy checkbox.
  7. Choose Apply... from the Actions pane.
  8. Choose URL Rewrite... from the Actions pane.
  9. Choose Add Rule(s)... in the Actions pane.
  10. Choose a blank inbound rule.
  11. Fill the Name field as desired.
  12. In the Match URL section, fill the Pattern field with the a regular expression to match the old endpoint's path (^message/endpoint\.ashx$ in the example).
  13. In the Conditions section, click Add....
  14. In the Condition input field, enter {SERVER_PORT}.
  15. Fill the Pattern field with a regular expression to match the old endpoint's port (^8000$ in the example).
  16. Click OK.
  17. In the Action section, fill the Rewrite URL field with the Data Hub endpoint's URL (http://localhost/endpoint in the example).
  18. Choose Apply... from the Actions pane.
  19. Close the IIS Manager.

Data Hub User Guide Version 1.3.0. Copyright © 2014 PreEmptive Solutions, LLC