ServiceControl relies on a defined set of queues for each instance type to ingest, process, and optionally forward messages. These queues are created during instance setup and vary depending on transport.
Queue Setup
Queues are only created during "Setup". Setup is run when an instance is created or updated. The simplest way to configure ServiceControl queues during installation is by using:
- ServiceControl Management Utility (SCMU) or
- PowerShell scripts or
- Container flags like
--setup
or--setup-and-run
These queues can also be manually created before deploying a ServiceControl instance. The technique used will differ depending on the transport in use:
ServiceControl instances do not subscribe to any events, and so do not require any subscriptions to be configured.
The following is an overview of all queues based on the default instance names.
Queue | Error Instance | Audit Instance | Monitoring Instance | Purpose |
---|---|---|---|---|
error | CR | Reads failed messages | ||
audit | CR | Reads audited messages | ||
error.log | CR | Forwards copy of failed messages | ||
audit.log | CR | Forwards copy of audited messages | ||
particular.monitoring | CR | Receives heartbeats, checks | ||
particular.servicecontrol | CR | W | Input queue for error/heartbeat | |
particular.servicecontrol.audit | CR | W | Input queue for audit instance | |
particular.servicecontrol.error | CW | Internal error queue | ||
particular.servicecontrol.audit.error | CW | Internal error queue for audit | ||
particular.servicecontrol.staging | CRW | Temporary queue for retries | ||
servicecontrol.throughputdata | CR | W | Tracks metrics / throughput |
R = Read (Dequeue) W = Write (Enqueue) C = Create
Error instance
The ServiceControl Error instance uses dedicated queues to receive failed messages and control signals necessary for tracking and recovery operations.
Failed messages queue
When an NServiceBus endpoint is unable to process a message, after exhausting the configured number of retries, it will forward a copy of the message to an error queue which by default is named as error
. The ServiceControl error instance reads messages from this queue and persists them in its embedded RavenDB database, marking them as candidates for retry or inspection.
- Default name: error
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | Write | Failed message configuration |
ServiceControl Error instance | Read | ServiceBus/ErrorQueue |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | - |
Input queue
Each ServiceControl Error instance has an input queue (also called the control queue) which accepts control messages from NServiceBus endpoints, and from ServiceControl instances. These control messages include:
- Heartbeats
- Custom checks
- Coordination messages (from the Audit instance)
When plugins like heartbeats or custom checks are used, they should be configured to send messages to this input queue.
- Queue name Template:
<instance name> - Default name: Particular.ServiceControl
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | Write | Heartbeats plugin and Custom checks plugin |
ServiceControl Error instance | Create/Read/Write | ServiceControl/InstanceName |
ServiceControl Audit instance | Write | ServiceControl.Audit/ServiceControlQueueAddress |
ServiceControl Monitoring instance | - |
The ServiceControl Audit instance sends a control message to the ServiceControl Error instance when it encounters an endpoint for the first time, and when a retried message has been audited to indicate that the retry was a success.
Error queue
The ServiceControl Error instance uses an internal queue to handle processing failures that occur during ingestion from the main error queue. If ServiceControl encounters a problem while reading or deserializing a message from the external error queue, it will forward a copy to this internal error queue to prevent message loss and allow for diagnosis or recovery.
- Template:
<instance name>. Error - Default name: Particular.ServiceControl.Error
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | Create/Read/Write | Based off of instance name |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | - |
The ServiceControl Error instance includes a built-in custom check that monitors this internal queue. If messages are detected, the check can raise alerts in ServicePulse to notify of ingestion issues.
Staging queue
The Staging queue is used exclusively by the ServiceControl Error instance to temporarily hold messages during the retry process. When a user initiates a retry in ServicePulse, failed messages are moved into this queue before being re-dispatched to their original endpoint.
This queue exists only during retries. Once messages are dispatched back to their original destination, they are removed from the staging queue. It is created automatically during setup and used internally by ServiceControl — endpoints do not interact with it directly.
- Template:
<instance name>. staging - Default name: Particular.ServiceControl.staging
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | Create/Read/Write | Based off of instance name |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | - |
Failed messages forwarding queue
If forwarding is enabled, the ServiceControl Error instance will forward a copy of each successfully ingested failed message to a designated log queue. These queues are not directly managed by ServiceControl and are meant as points of external integration.
- Template:
<failed messages queue>. log - Default name: error.log
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | Create/Write | ServiceBus/ErrorLogQueue |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | - |
Endpoint instance input queues
During a retry operation, the ServiceControl Error instance re-dispatches failed messages back to the original endpoint's input queue. This queue is the same one where the endpoint normally receives operational messages.
ServiceControl uses the NServiceBus.
header (present on the original failed message) to determine which queue to target. The endpoint then reprocesses the message as if it had just arrived for the first time. Once a message is retried and dispatched to the original endpoint, the endpoint attempts to process it again.
If the message is successfully processed, it is typically forwarded to the
audit
queue. The Audit instance then ingests the message, confirming that the retry was successful — triggering status updates in ServicePulse that mark the message as resolved.If the message fails again during processing, it is returned to the
error
queue. The Error instance ingests it as a newly failed message, and it reappears in ServicePulse for further analysis or retry attempts
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | Create/Read | Endpoint name |
ServiceControl Error instance | Write | Configured via the NServiceBus. header on failed messages |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | - |
Throughput data
The Throughput Data queue is used to collect and share performance metrics between ServiceControl instances. It enables visibility into message processing rates, endpoint activity, and system health.
- Default name: ServiceControl.ThroughputData
Component | Access requirements | Configuration |
---|---|---|
ServiceControl Error instance | Create/Read | Configured via the LicensingComponent/ setting |
ServiceControl Monitoring instance | Write | Queue configured via [Monitoring/ ]/servicecontrol/monitoring-instances/configuration.md#usage-reporting-monitoringservicecontrolthroughputdataqueue) |
Audit instance
The ServiceControl Audit instance requires specific queues to ingest successfully processed messages from endpoints and support internal operations.
Audit queue
When auditing is enabled, NServiceBus endpoints send a copy of every successfully processed message to the audit
queue. The Audit instance reads from this queue and persists the messages to its embedded RavenDB database for visualization and analysis (e.g., ServicePulse).
If the Saga Audit plugin is used, it should be configured to send messages to the audit queue as well.
- Default name: audit
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | Create/Write | Audit configuration and Saga Audit plugin |
ServiceControl Error instance | - | |
ServiceControl Audit instance | Create/Read | ServiceBus/AuditQueue |
ServiceControl Monitoring instance | - |
Input queue
Each ServiceControl Audit instance defines an input queue, even though it is currently not actively used for message ingestion. However, its presence is required for the instance to operate correctly.
- Template:
<instance name> - Default value: Particular.ServiceControl.Audit
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | - | |
ServiceControl Audit instance | Create/Read | ServiceControl.Audit/InstanceName |
ServiceControl Monitoring instance | - |
Error queue
If a ServiceControl Audit instance encounters a message it cannot process — due to deserialization issues, invalid headers, or other ingestion failures — it forwards that message to a dedicated error queue for isolation and troubleshooting. This queue is created and written to by the Audit instance itself. It is not consumed by other ServiceControl components and is intended for diagnostic purposes.
- Template:
<instance name>. Error - Default name: Particular.ServiceControl.Audit.Error
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | - | |
ServiceControl Audit instance | Create/Write | Based off of instance name |
ServiceControl Monitoring instance | - |
Audit forwarding queue
If Audit Forwarding is enabled, the ServiceControl Audit instance sends a copy of each successfully ingested audit message to a designated log queue. This allows external systems to consume or archive audit data independently of ServiceControl.
- Template:
<audit queue name>. log - Default name: audit.log
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | - | |
ServiceControl Audit instance | Create/Write | ServiceBus/AuditLogQueue |
ServiceControl Monitoring instance | - |
Monitoring instance
The Monitoring instance collects performance and health data from endpoints using the NServiceBus Metrics plugin. It uses a set of queues to ingest, forward, and share this data with other ServiceControl components.
Input queue
Endpoints send monitoring data to the Monitoring instance via its input queue. Messages are sent to this queue even if the Monitoring instance is offline. Once available, it will process any backlog.
- Template:
<instance name> - Default value: Particular.Monitoring
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | Write | Monitoring plugin |
ServiceControl Error instance | - | |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | Create/Read | Monitoring/InstanceName |
Error queue
If the Monitoring instance fails to process a message — due to deserialization errors or unsupported formats — it forwards the message to a configured error queue.
- Default name: error
- Configure via: Configuration Setting
Monitoring/
ErrorQueue
Component | Access requirements | Configuration |
---|---|---|
NServiceBus endpoints | - | |
ServiceControl Error instance | - | |
ServiceControl Audit instance | - | |
ServiceControl Monitoring instance | Create/Write | Monitoring/ErrorQueue |
Throughput data
This queue enables the Monitoring instance to share performance metrics with the Error instance — such as message rates and endpoint activity.
- Queue name: ServiceControl.ThroughputData
Component | Access requirements | Configuration |
---|---|---|
ServiceControl Error instance | Create/Read | Configured via the LicensingComponent/ setting |
ServiceControl Monitoring instance | Write | Queue configured via Monitoring/ |
Both instances must be configured to use the same queue name to ensure metrics are exchanged correctly.