Monitoring NServiceBus solutions: Getting started

Component: NServiceBus
NuGet Package NServiceBus (6.x)
The monitoring tools described on this page are in Beta and are 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.

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 it's 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 fowarded 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 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 be used to 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 ServiceControl instance

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

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 runs on. Depending on the transport you may be required to add an additional connection string.

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

Click the Add button. Your ServiceControl instance will start and be listed 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 link. 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 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 instance 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 runs on. Depending on the transport selected you may be required 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 link. 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

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.

If you already have ServicePulse running on your machine you will need to uninstall it and download the latest version in order to be able to configure ServicePulse to connect to a ServiceControl Monitoring instance.

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 needs to 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");
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:

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 it's 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 you need to install the ServiceControl metrics package. From the Visual Studio Package Manager Console window, execute the following:

Install-Package NServiceBus.Metrics.ServiceControl -Version 2.0.0-beta0003

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)
);
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.

Smoke Test

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

ServicePulse - Monitoring Tab - With Endpoints

Next Steps


Last modified