NServiceBus monitoring setup

This tutorial will guide you through the steps required to set up your NServiceBus solution for monitoring with the Particular Service Platform. The tutorial assumes that you're configuring monitoring for an existing solution and doesn't explain how to create a new application. See the quick start tutorial for details on how to do that.

• Component overview
• Setting up Particular Service Platform
  • Install ServiceControl
  • Create ServiceControl instance
  • Create ServiceControl Monitoring Instance
• Configure NServiceBus endpoints
  • Error
  • Audit
  • Monitoring

Component overview

A running NServiceBus system can be configured to send data about its operations to three main queues:

• Monitoring: Each endpoint will gather and send metric data to this queue. This data holds information about the health and performance of an endpoint.
• Audit: When an endpoint successfully processes a message, a copy of the message will be forwarded to this queue. The audited message will have additional headers which contain data about the processing of the message.
• Error: When an endpoint fails to process a message (after exhausting automated retry attempts), a copy of the message is forwarded to this queue. The failed message will have additional headers which contain data about the failed attempt to process the message.

Any solution using the NServiceBus package can be configured to send messages to the Audit and Error queues. In order to send data to the Monitoring queue, two additional packages are required:

• NServiceBus.Metrics: hooks into the NServiceBus pipeline to gather and expose metrics.
• NServiceBus.Metrics.ServiceControl: buffers the data generated by NServiceBus.Metrics and periodically sends it to the monitoring queue. This package also instruments outgoing messages with additional headers that are used to estimate queue length.

ServiceControl is a suite of back-end tools that collect useful information about your running system. A monitoring system back-end consists of two different components:

• ServiceControl instance: collects messages from the audit and error queues.
• Monitoring instance: collects data from the monitoring queue about all of the endpoints in an NServiceBus system.

Both of these instance types can be set-up and managed with the ServiceControl Management Utility.

ServicePulse is a web application that connects to ServiceControl and provides production monitoring and recoverability. It contains pages to visualize the monitoring data in a monitoring instance. It can also be used to review and manage failed messages that are managed by a ServiceControl instance.

Setting up the Particular Service Platform

In order to configure an environment for monitoring with the Particular Service Platform you will need to install and configure the components in the order listed.

Install ServiceControl

The main ServiceControl installer includes a desktop utility called the ServiceControl Management Utility which can create and manage both types of instance.

Download and run the latest ServiceControl installer.

Once it has finished installing, run the ServiceControl Management Utility.

Create a ServiceControl instance

In the ServiceControl Management Utility, click + New and select ServiceControl instance from the list of options.

Scroll down to the Transport Configuration section. Select the transport that your NServiceBus system uses. Depending on the transport you may need to add an additional connection string.

Under Audit Forwarding select either On or Off. If you are not currently using an audit queue, you can safely turn this off. See audit forwarding for more information.

Click the Add button. Your ServiceControl instance will start and appear on the main page of the ServiceControl Management Utility.

The listing for the ServiceControl instance includes a URL. This URL will be needed when installing ServicePulse below.

Create a ServiceControl monitoring instance

A monitoring instance collects data from the monitoring queue and aggregates information from all of the endpoints in the system.

In the ServiceControl Management Utility, click + New and select monitoring endpoint from the list of options.

Scroll down to the Transport Configuration section. Select the transport that your NServiceBus system uses. Depending on the transport selected you may need to add an additional connection string.

Click the Add button. Your monitoring instance will start and be listed on the main page of the ServiceControl Management Utility.

The listing for the monitoring instance includes a URL. This URL will be needed when installing ServicePulse below.

Install ServicePulse

ServicePulse is a web application for production monitoring and recoverability. It connects to a monitoring instance to display monitoring data and to a ServiceControl instance to display recoverability data.

Download and run the latest ServicePulse installer.

On the ServicePulse Configuration screen ensure that Recoverability is enabled and enter the URL of the ServiceControl instance API. Check the box marked Monitoring and enter the URL of the monitoring instance API.

You can find the URLs for each instance API in the ServiceControl Management Utility.

Launch ServicePulse and navigate to the Monitoring tab.

Configure NServiceBus endpoints

In order to be monitored by the Particular Service Platform, each endpoint must be configured to send data to three different queues: error, audit, and monitoring.

It is recommended to go through this entire process for a single endpoint and ensure that it is working before continuing on to the next endpoint.

Error

Whenever an NServiceBus endpoint is unable to process a message (even after several attempts) it will forward the message to the error queue. Each environment (such as dev, test, QA, production) should contain a single error queue and should not share an error queue with another environment.

The error queue is created with a new ServiceControl instance. By default, it is named error.

Configure your endpoint to send failed messages to the error queue.

Add the following code to your endpoint configuration:

endpointConfiguration.SendFailedMessagesTo("error");

Audit

Whenever an NServiceBus endpoint successfully processes a message, it can be configured to send a copy to a centralized audit queue. Each environment should contain a single audit queue and should not share an audit queue with another environment.

The audit queue is created with a new ServiceControl instance. By default, it is named audit.

Configure your endpoint to send processed messages to an audit queue.

Add the following code to your endpoint configuration:

endpointConfiguration.AuditProcessedMessagesTo("audit");

Monitoring

An NServiceBus endpoint can be configured to send data about its health and performance to a centralized monitoring queue. Each environment should contain a single monitoring queue and should not share a monitoring queue with another environment.

The monitoring queue is created with a new monitoring instance. By default, it is named Particular.Monitoring.

To get an NServiceBus endpoint to send metric data to the monitoring queue, install the NServiceBus.Metrics.ServiceControl NuGet package. From the Visual Studio Package Manager Console window, execute the following:

Install-Package NServiceBus.Metrics.ServiceControl -Version 3.0.6

You can then enable monitoring and configure the location of the monitoring queue. Add the following code to your endpoint configuration:

var metrics = endpointConfiguration.EnableMetrics();

metrics.SendMetricDataToServiceControl(
    serviceControlMetricsAddress: "Particular.Monitoring",
    interval: TimeSpan.FromSeconds(2)
);

Smoke Test

Now that everything is installed, run the system and open ServicePulse. In the monitoring tab, you should see a list of running endpoints.

Next Steps

• Learn more about ServiceControl
• Learn more about ServicePulse
• Learn more about the NServiceBus.Metrics plugin