Getting Started

How does ServiceControl work?

ServiceControl is a background process that will collect and store data and make it available via an HTTP API to ServicePulse and ServiceControl.

How ServiceControl receives data

For each ServiceControl service type (i.e. error, audit, and monitoring) there is different data available that must be provided by user-built NServiceBus endpoints.

graph LR subgraph Endpoints Error Plugins[Saga audit<br>Heartbeats<br>Custom checks] Audit Monitoring end Audit -- Audit<br>data --> AuditQ(Audit queue) AuditQ --> ServiceControlAudit[ServiceControl<br>audit instance] ServiceControlAudit --> AuditLog(Audit.Log<br>queue) ServiceControlAudit -. Integration<br>events .-> Watchers Plugins -- Plugin data --> SCQ Plugins -- SagaAudit<br>data --> AuditQ(Audit queue) SCQ(ServiceControl<br>queue) --> ServiceControlError Error -- Error<br>data --> ErrorQ(Error queue) ErrorQ --> ServiceControlError[ServiceControl<br>error instance] ServiceControlError --> ErrorLog(Error.Log<br>queue) ServiceControlError -. Integration<br>events .-> Watchers[Subscribers] Monitoring --> MonQ(Monitoring queue) MonQ --> ServiceControlMonitoring[Monitoring instance] classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF classDef ServiceControlInstance fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px classDef Plugin fill:#00729C,stroke:#000,color:#ddd class ServiceControlError ServiceControlInstance class ServiceControlAudit ServiceControlInstance class ServiceControlMonitoring ServiceControlInstance class Watchers Endpoints class Plugins Plugin class Audit Plugin class Error Plugin class Monitoring Plugin

Error instances

Recoverability is an important feature in NServiceBus. It enables automatic retries and continuity within a system, as failed messages will be moved aside to allow other messages to be processed while the errors are investigated. Those error messages contain business data that must eventually be processed.

NServiceBus will move messages it cannot process to an error queue. This is where ServiceControl comes into play to consume these messages. ServiceControl will pick up the message and store it in an internal database. ServiceControl uses an embedded RavenDB instance for the internal database. After it is stored in the database, the message is made available to ServicePulse and ServiceInsight for visualization, retries, and other operations.

Find out more about failed messages in ServicePulse.

Audit instances

To enable ServiceInsight to visualize the message flow through the system, it must have access to every message that has been successfully processed by the system. This requires endpoints to enable auditing. ServiceControl consumes these messages and stores them in its internal database.

ServiceInsight will retrieve the data from ServiceControl via the HTTP API and use header information (added by NServiceBus during message processing) to figure out which message caused other messages to be sent, including which sagas were accessed when the SagaAudit plugin is configured in an endpoint.

Monitoring instances

For ServicePulse to report metrics on logical endpoints, endpoint instances and on specific messages, each endpoints needs to be enabled to forward metrics to ServiceControl. ServicePulse will then be able to retrieve the data from ServiceControl via the HTTP API.


ServiceControl consumes messages from the audit and error queues. That is, it removes all messages from those queues. If a copy of those messages is required for further processing, configure audit forwarding and/or error queue forwarding.