ServiceControl Endpoint Plugins

ServiceControl is the backend service for ServiceInsight, ServicePulse, and third-party integration. It collects and stores information from monitored NServiceBus endpoints and exposes this information for consumption by various clients via a HTTP API.

When ServiceControl is introduced into an existing environment the standard behavior of error and audit queues will change. When ServiceControl is not monitoring the environment failed messages will remain in the configured error queue and audit messages in the configured audit queue, as soon as ServiceControl is installed and configured messages, in both queues, will be imported by ServiceControl.

Plugins collect information from NServiceBus and are deployed together with each NServiceBus endpoint. These plugins are optional from the perspective of the NServiceBus framework itself (they are not required by the endpoint), but they are required in order to collect the information that enables ServiceControl (and its clients) to provide the relevant functionality for each plugin.

ServiceControl provides the monitoring capability by analyzing the configured error and audit queues. It can extract information like endpoint name, queue name and, in case of error messages, the exception stack trace, etc. This information is stored in a built-in internal database.

Configuring an endpoint to be monitored by ServiceControl

To allow ServiceControl to monitor endpoints:

  1. ServiceControl should be installed and at least one instance should be configured using the same transport as that of the endpoints that are being monitored.
  2. For every endpoint that is being monitored by ServiceControl, configure the endpoint for auditing. Make sure that the audit queue is the same as the audit queue that ServiceControl is configured with.
  3. For every endpoint that is being monitored by ServiceControl, configure recoverability. Make sure that the error queue is the same as the error queue that ServiceControl is configured with.

Installing and Deploying Plugins

The ServiceControl plugins are deployed with the endpoints they are monitoring. It is possible add a plugin to an endpoint during development, testing, or production:

  • During development, add the relevant plugin NuGet package to the endpoint's project in Visual Studio using the NuGet.
  • When in production, add the plugin dlls to the BIN directory of the endpoint, specify the ServiceControl via AppSettings (see below) and restart the endpoint process for the changes to take effect and the plugin to be loaded.

Related articles

ServiceControl offers the following endpoint plugins:

  • Heartbeat Plugin - Enables endpoint health monitoring. It sends heartbeat messages at a regular interval from the endpoint to ServiceControl to help determine whether the endpoint is active. This information is shown in ServicePulse.
  • Saga Plugin - Enables the Saga visualization capabilities useful for debugging during development. The Saga message behavior and the saga state changes as the Saga is being processed are sent to ServiceControl. This information is shows in ServiceInsight. This plugin is only for development purposes and should not be used in production.
  • Custom Check Plugin - Enables custom monitoring abilities for endpoints by allowing the developer to define a set of conditions that needs to be checked. This plugin will report the results of these custom checks to ServiceControl.

Connecting to ServiceControl

Once deployed on an active endpoint, the endpoint sends plugin-specific information to ServiceControl. Plugins send messages using the defined endpoint transport to the ServiceControl queue. Location of ServiceControl queue is determined by the following:

  1. Endpoint's configuration file Check for an appSetting named ServiceControl/Queue e.g. <add key="ServiceControl/Queue" value="particular.servicecontrol"/>.
  2. Code base API (only available for Version 2 or greater of the plugins that target NServiceBus Version 6) See specific plugin pages.
Endpoint with plugins installed will shut down when the ServiceControl queue setting has not been set or when the plugin is unable to communicate with the configured ServiceControl queue.

The ServiceControl queue (and all other ServiceControl related sub-queues) are created during the installation phase of ServiceControl. The queue name is based on the Window Service name. If ServiceControl is installed with a Windows Service name other than the default name then the convention based detection does not apply. In this scenario the configuration setting ServiceControl/Queue must be set to the correct queue name.

ServiceControl instances configured to use the MSMQ transport must be installed on the same machine as the error and audit queues.


Related Articles

Last modified