OVERVIEW

Installation

• Choosing a Host
• Deployment
• Reinstalling or Upgrading
• Installation Defaults

Configuration

• Instrumenting Applications
• Dispatch Service
• Endpoint Web Service
• Customer Experience Improvement Program

Management

• Restarting
• Performance Tuning

Monitoring

• Event Log
• WMI Counters
• RabbitMQ Monitoring

Troubleshooting

• Troubleshooting
• Deleting Messages
• HTTP Details

Advanced Configuration

• RabbitMQ
• Logging

LICENSE

RabbitMQ

The Data Hub uses the third-party RabbitMQ messaging system to store messages before they are dispatched. The default configuration, where an instance of RabbitMQ is installed on the same machine as the Data Hub, should typically not need to be changed. However, if you need to change e.g. the host or port that they use to communicate, instructions for doing so have been provided here and in the subsections below.

WARNING: Changes to the connection settings must be coordinated across three locations: RabbitMQ, the Endpoint Web Service, and the Dispatch Service. It is easiest and safest to stop all three services (RabbitMQ last), make the changes, and start them again (RabbitMQ first) - see the subsections of Restarting the Entire Data Hub. This will cause a temporary outage at the Endpoint.

Data Hub Parameters

The Data Hub has separate configuration files for the Dispatch Service and for the Endpoint. Each component has the same settings, described below, located in the <appsettings> section of their respective file.

The Endpoint Web Service settings are in [Application folder]\Web\Web.config.

The Dispatch Service settings are in [Application folder]\DispatchService\HubDispatchService.exe.config.

The settings are as follows:

• RabbitServerAddress
  • The IP or hostname of the RabbitMQ instance.
  • Default: 127.0.0.1
• RabbitServerPort
  • The port on which AMQP (data transfer) connections are made.
  • Default: 5672 (the AMQP default)
• RabbitServerPortalPort
  • The port on which RabbitMQ management plugin connections are made.
  • Default: 15672
• RabbitServerVirtualHost
  • The virtual host on the RabbitMQ server to use.
  • Default: /
• RabbitServerUsername
  • The username which is used for connections to RabbitMQ.
  • This user must be an administrator user.
  • Default: guest
• RabbitServerPassword
  • The password which is used for the above user.
  • This user must have a password.
  • Default: guest
• QueuingTimeoutInSeconds
  • Time, in whole seconds, that Data Hub will wait for RabbitMQ to complete an action before giving up.
  • Data Hub endpoint will wait for this amount of time for RabbitMQ to enqueue a message before sending a 500 response back to the client.
  • Default: 10
• QueueCountMonitoringIntervalSeconds
  • The frequency, in whole seconds, at which the Data Hub will query RabbitMQ to measure queue sizes for reporting as WMI counters.
  • Default: 1

RabbitMQ Parameters

The Data Hub-provided installation of RabbitMQ has been pre-configured to work with the Data Hub. The relevant connection settings are in the RabbitMQ configuration file, which is in the non-standard location of [RabbitMQ data folder]\rabbitmq.config.

Details about the RabbitMQ configuration settings can be found in the online documentation for the RabbitMQ configuration file.

These settings can be changed using JSON syntax.

Parameters include:

• rabbit.tcp_listeners
  • An array of interfaces RabbitMQ will listen on for AMQP connections, each expressed in the form {hostname, port}.
  • Pre-configured setting: {"127.0.0.1", 5672}.
• rabbit.collect_statistics_interval
  • The time, in milliseconds, between RabbitMQ updating its statistical tracking (e.g. the size of queues).
  • Pre-configured setting: 1000.
• rabbitmq_management.listener.ip
  • The IP for the RabbitMQ management plugin to listen on.
  • Pre-configured setting: 127.0.0.1.
• rabbitmq_management.listener.port
  • The port for the RabbitMQ management plugin to listen on.
  • Pre-configured setting: 15672.

RabbitMQ Users

The Data Hub installation of RabbitMQ uses its default user settings, with one administrator account named guest, with the password guest. This installation only allows access to RabbitMQ on the same machine, but you may wish to create another administrator account and delete the default one for security reasons. Or, you may wish to create a user with monitoring privileges only, to prevent accidental changes using the management console.

Adding a Monitoring User

A monitoring user can see statistics on RabbitMQ, but cannot make any changes to the user configuration, nor affect the queues in any way.

To create such a user:

1. Using a web browser, browse to http://localhost:15672/#/users.
   • If not using the default RabbitMQ installation, use the appropriate URL instead.
2. Log in using an account with administrator privileges (guest/guest by default).
3. Locate the Add a user section. Expand if necessary.
4. Enter the Username and Password.
5. Click [Monitoring].
6. Click Add user.
7. Locate the All users section. Expand if necessary.
8. Click on the name of the user you just created.
9. Locate the Permissions section. Expand if necessary.
10. Under Set permission, choose the appropriate virtual host (/ by default).
11. Clear the Configure regexp, Write regexp, and Read regexp fields entirely.
12. Click Set permission.

Adding an Administrator User

An administrator user can modify all elements of RabbitMQ, including changing the user configuration and purging queues.

To create such a user:

1. Using a web browser, browse to http://localhost:15672/#/users.
   • If not using the default RabbitMQ installation, use the appropriate URL instead.
2. Log in using an account with administrator privileges (guest/guest by default).
3. Locate the Add a user section. Expand if necessary.
4. Enter the Username and Password.
5. Click [Admin].
6. Click Add user.
7. Locate the All users section. Expand if necessary.
8. Click on the name of the user you just created.
9. Locate the Permissions section. Expand if necessary.
10. Under Set permission, choose the appropriate virtual host (/ by default).
11. Ensure the Configure regexp, Write regexp, and Read regexp fields are each set to .*.
12. Click Set permission.

Removing a User

Warning: You must reconfigure the Data Hub connections to use another administrator user before removing the user currently used by the Data Hub (default is guest).

Warning: Do not remove all administrator users. If you do so, you will probably have to uninstall and reinstall, causing data loss.

To remove a user:

1. Using a web browser, browse to http://localhost:15672/#/users.
   • If not using the default RabbitMQ installation, use the appropriate URL instead.
2. Log in using an account with administrator privileges (guest/guest by default).
3. Locate the All users section. Expand if necessary.
4. Click on the name of the user you wish to remove.
5. Locate the Delete this User section. Expand if necessary.
6. Click Delete.
7. Confirm that you wish to permanently delete the user.