Monitoring NServiceBus solutions: Getting started

Component: NServiceBus
NuGet Package NServiceBus (6.5-pre)
This page targets a pre-release version and is subject to change prior to the final release.

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.

At the moment systems using the Learning Transport can't be monitored as described below. If you're using solution from other tutorials or samples, ensure that you've configured NServiceBus to use another transport.

Component overview

graph TD subgraph Endpoint nsb(NServiceBus) --> metrics metrics(NServiceBus.Metrics) --> plugin plugin(NServiceBus.Metrics.ServiceControl) end plugin --> q(Monitoring Queue) nsb --> auditQ(Audit Queue) nsb --> errorQ(Error Queue) subgraph ServiceControl scinstance scmonitoring end auditQ --> scinstance(ServiceControl Instance) errorQ --> scinstance q --> scmonitoring[Monitoring Instance] scmonitoring --> pulse[ServicePulse] scinstance --> pulse

A running NServiceBus system can be configured to send data about its operation 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:

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.

The easiest way to install the Platform tools is by running the Particular Platform Installer which automates downloading and installing all tools. Individual installers can still be downloaded for environments that are not directly connected to the internet.

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.

You should run the latest version of the installer, even if you already have ServiceControl installed. Only versions 1.43 and above of the ServiceControl Management Utility can create and manage monitoring instances.

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

Create a ServiceControl instance

You can use an existing ServiceControl instance if it is version 1.43 or higher.

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

ServiceControl Management Utility - Add new ServiceControl instance

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.

ServiceControl Management Utility - List instance - ServiceControl instance

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

Creating the ServiceControl instance will also create the audit and error queues if they did not already exist. By default these are called audit and error respectively.

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.

ServiceControl Management Utility - Add new Monitoring instance

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.

ServiceControl Management Utility - List instance - Monitoring instance

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

Creating the monitoring instance will also create the monitoring queue if it did not already exist. By default this queue is called Particular.Monitoring.

Install ServicePulse

Make sure that ServiceControl and ServiceControl monitoring instances are added first.

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.

In order to configure ServicePulse to connect to a ServiceControl monitoring instance you must download the latest version, then uninstall your current version and install the downloaded version.

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.

ServicePulse Installer - ServiceControl configuration

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

ServiceControl Management Utility - Instance List - Api Addresses Highlighted

Launch ServicePulse and navigate to the Monitoring tab.

ServicePulse - Monitoring Tab - Empty

If monitoring was not enabled during installation, the monitoring tab will not be visible.

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:

6.x - 6.4 NServiceBus
endpointConfiguration.SendFailedMessagesTo("error");
If you are using the MSMQ transport then you also need to specify the machine where the error queue is located. i.e. error@MACHINENAME. This should be the same machine where your ServiceControl instance is installed.

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:

6.x - 6.4 NServiceBus
endpointConfiguration.AuditProcessedMessagesTo("audit");
If you are using the MSMQ transport then you also need to specify the machine where the audit queue is located. i.e. audit@MACHINENAME. This should be the same machine where your ServiceControl instance is installed.

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:

6.x - 6.4 NServiceBus
Install-Package NServiceBus.Metrics.ServiceControl -Version 2.0.1

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

6.x - 6.4 NServiceBus
var metrics = endpointConfiguration.EnableMetrics();

metrics.SendMetricDataToServiceControl(
    serviceControlMetricsAddress: "Particular.Monitoring",
    interval: TimeSpan.FromSeconds(2)
);
If you are using the MSMQ transport then you also need to specify the machine where the monitoring queue is located. i.e. Particular.Monitoring@MACHINENAME. This should be the same machine where your monitoring instance is installed.
When using the MSMQ transport it is also necessary to install queue length metrics reporter package. The queue length troubleshooting guide contains more details on possible problems with the monitoring setup.

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.

ServicePulse - Monitoring Tab - With Endpoints

Next Steps


Last modified