Heartbeat Plugin

The Heartbeat plugin enables endpoint health monitoring in ServicePulse. It sends heartbeat messages from the endpoint to the ServiceControl queue. These messages are sent every 10 seconds (by default).

An endpoint that is marked for monitoring (by ServicePulse) will be expected to send a heartbeat message within the specified time interval. As long as a monitored endpoint sends heartbeat messages, it is marked as "active". Marking an endpoint as active means it is able to properly and periodically send messages using the endpoint-defined transport.

Note that even if an endpoint is able to send heartbeat messages and it is marked as "active", other failures may occur within the endpoint and its host that may prevent it from performing as expected. For example, the endpoint may not be able to process incoming messages, or it may be able to send messages to the ServiceControl queue but not to another queue. To monitor and get alerts for such cases, develop a custom check using the CustomChecks plugin.

If a heartbeat message is not received by ServiceControl from an endpoint, that endpoint is marked as "inactive".

An inactive endpoint indicates that there is a failure in the communication path between ServiceControl and the monitored endpoint. For example, such failures may be caused by a failure of the endpoint itself, a communication failure in the transport, or when ServiceControl is unable to receive and process the heartbeat messages sent by the endpoint.

Deprecated NuGet Packages

The following Heartbeat plugin packages have been deprecated and unlisted. If using one of these versions replace package references to use NServiceBus.Heartbeat.

• ServiceControl.Plugin.Heartbeat
• ServiceControl.Plugin.Nsb5.Heartbeat
• ServiceControl.Plugin.Nsb6.Heartbeat

Configuration

ServiceControl Queue

Plugins send messages using the defined endpoint transport to ServiceControl. The plugin must be configured with the location of the ServiceControl input queue. This queue is created during the installation of ServiceControl. The queue name is based on the ServiceControl instance name which is visible in the ServiceControl Management utility.

Configure the ServiceControl queue via code:

var endpointConfiguration = new EndpointConfiguration("myendpoint");
endpointConfiguration.HeartbeatPlugin(
    serviceControlQueue: "ServiceControl_Queue");

Configure the ServiceControl queue via config:

<appSettings>
  <add key="ServiceControl/Queue"
       value="particular.servicecontrol@machine" />
</appSettings>

Heartbeat Interval

ServiceControl heartbeats are sent, by the plugin, at a predefined interval of 10 seconds. The interval value can be overridden on a per endpoint basis adding the following application setting to the endpoint configuration file:

<appSettings>
  <add key="Heartbeat/Interval"
       value="00:00:30"/>
</appSettings>

Where the value is convertible to a TimeSpan value. The above sample is setting the endpoint heartbeat interval to 30 seconds.

Or using code:

var endpointConfiguration = new EndpointConfiguration("myendpoint");
endpointConfiguration.HeartbeatPlugin(
    serviceControlQueue: "ServiceControl_Queue",
    frequency: TimeSpan.FromMinutes(2));

When configuring heartbeat interval, ensure ServiceControl setting HeartbeatGracePeriod is greater than the heartbeat interval.

Time-To-Live (TTL)

When the plugin sends heartbeat messages, the default TTL is fixed to four times the configured value of the Heartbeat interval.

TTL is now configurable, as of Version 1.1.0

Add the app setting in app.config as shown to configure the TTL to a custom value instead of the default value based on heartbeat interval. Provide the timespan string for the value as shown. In this example, a heartbeat message will be sent every 30 seconds and the TTL for the heartbeat message is 3 minutes.

<appSettings>
  <add key="Heartbeat/Interval"
       value="00:00:30"/>
  <add key="Heartbeat/TTL"
       value="00:03:00"/>
</appSettings>

Or using code:

var endpointConfiguration = new EndpointConfiguration("myendpoint");
endpointConfiguration.HeartbeatPlugin(
    serviceControlQueue: "ServiceControl_Queue",
    frequency: TimeSpan.FromSeconds(30),
    timeToLive: TimeSpan.FromMinutes(3));

Disabling plugin

var endpointConfiguration = new EndpointConfiguration("myendpoint");
endpointConfiguration.DisableFeature<Heartbeats>();

Expired heartbeat messages

Heartbeat messages have a time to be received (TTBR) set based on the TTL value. If ServiceControl does not consume the heartbeat messages before the TTBR expires then those messages may be discarded. Transports like MSMQ and ASB support DLQ and the expired heartbeat messages can be explicitly configured to be forwarded to the DLQ instead of being discarded.

MSMQ

Although NServiceBus configures the use of DLQ by default, messages that are defined with TTBR will not be automatically forwarded to the DLQ and will be discarded. Configuration can be specified to override this behavior so that these messages can be forwarded to the DLQ.

ASB

Forwarding messages with expired TTL to DLQ is a configuration that needs to be set on the destination queue which is the ServiceControl queue for the heartbeat messages. In order to forward the heartbeat messages after the TTBR expiration to DLQ, ServiceControl needs to be explicitly configured by specifying EnableDeadLetteringOnMessageExpiration.