Send Metrics data to ServiceControl

The NServiceBus.Metrics.ServiceControl component enables sending monitoring data gathered with NServiceBus.Metrics to a ServiceControl.Monitoring service.

Configuration

To install the plugin in an endpoint, reference the NServiceBus.Metrics.ServiceControl NuGet package, which allows collection and propagation of metrics to ServiceControl.

It can be enabled via:

const string SERVICE_CONTROL_METRICS_ADDRESS = "particular.monitoring";

var metrics = endpointConfiguration.EnableMetrics();

metrics.SendMetricDataToServiceControl(
    serviceControlMetricsAddress: SERVICE_CONTROL_METRICS_ADDRESS,
    interval: TimeSpan.FromMinutes(1),
    instanceId: "INSTANCE_ID_OPTIONAL");

Service Control Metrics Address

The default instance name is particular.monitoring which is also used as the input queue for ServiceControl monitoring.

Interval

Specifies the maximum delay between sending metrics report messages.

The metrics plugin buffers measurements and sends a metric report message as soon as the buffer is half full, without waiting for the interval to elapse. When an endpoint instance is idle the plugin will still send a report at this interval so that ServiceControl monitoring knows that the instance is still running. When the endpoint is under load, the time between metric messages will be much shorter as the buffer fills faster.

The recommended value is between 10 and 60 seconds.

1. Smaller values result in ServiceControl monitoring view to be updated faster, especially on the 1-minute timescale
2. Larger values result in less frequent ServiceControl monitoring view updates only when an instance is not under heavy load. This isn't affecting the monitoring view with 10-minutes or larger timescales

It is recommended to use higher values for systems that can have many endpoint instances or use a transport that might be affected by rate limiting (often cloud-based).

Example:

If the system has 500 instances and the interval is set to 5 seconds, an idle system will send on average 6000 messages per minute (500 × 12), which is 100 per second.

Time To Be Received

By default, messages sent to the monitoring instance of ServiceControl have Time To Be Received set to 7 days. This value can be overridden when needed using following API:

metrics.SetServiceControlMetricsMessageTTBR(TimeSpan.FromHours(1));

Instance ID

Overrides the value ServiceControl monitoring uses to identify this endpoint instance, in place of $.diagnostics.hostid and $.diagnostics.hostdisplayname.

It is recommended to override the host id and host display name via NServiceBus core and to use the API without the InstanceId argument. By default, the monitoring plugin will use these values to identify the monitored endpoint instances in the user interface.

A human-readable value is passed in the following example:

const string SERVICE_CONTROL_METRICS_ADDRESS = "particular.monitoring";

var endpointName = "MyEndpoint";
var machineName = $"{Dns.GetHostName()}.{IPGlobalProperties.GetIPGlobalProperties().DomainName}";
var instanceIdentifier = $"{endpointName}@{machineName}";

var metrics = endpointConfiguration.EnableMetrics();

metrics.SendMetricDataToServiceControl(
    serviceControlMetricsAddress: SERVICE_CONTROL_METRICS_ADDRESS,
    interval: TimeSpan.FromMinutes(1),
    instanceId: instanceIdentifier);