ServiceControl Queues

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:

• Azure Service Bus
• Azure Storage Queues
• SQL Server
• MSMQ
• RabbitMQ
• Amazon SQS

The following is an overview of all queues based on the default instance names.

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

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

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

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

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

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.FailedQ 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

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

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

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

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

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

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

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

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

Both instances must be configured to use the same queue name to ensure metrics are exchanged correctly.