ATS Bus uses NServiceBus as its service bus framework. It's configured using ATS Bus Cockpit which allows the user to setup NserviceBus’s persistence, transport, serialization and recoverability.
Make sure that the settings are configured properly before starting a bus stop as the setup will apply to all the bus stops.
ATS Bus uses safe NServiceBus settings but the Particular ServiceControl hostname must be updated before starting the bus stops.
To monitor traffic on NServiceBus you can use ServiceInsight and ServicePulse.
In Cockpit select the General tab.
Click NServiceBus.
The NServiceBus dialog opens. Allowing you to configure settings for all bus stops.
NServiceBus supports multiple persistence (https://docs.particular.net/persistence/). Best practice is to install the persistence (SQL database) on the same node as the bus stop to prevent issues when the network connection fails.
The persistence settings configured in this section are applied to all bus stops. When using a central database (MS SQL), use the hostname of the database server, when using a local instance (side by side with the bus stop), use localhost as the hostname of the database server.
Microsoft SQL: This persistence requires an MS SQL Server / MS SQL Express database installed on the same node as the bus stop or on a central server. The persistence parameter is a connection string with the following format:
Data Source=server\instance;Database=PersistenceDatabase;User Id=LoginName;Password=LoginPassword;
Where
Data Source: The instance that hosts the database.
Database: The name of the database. The database must be created before the bus stop is started. The bus stop does not create the database.
User Id: The database login account.
Password: The password belonging to the login account.
Oracle: This persistence requires an Oracle database. The persistence paramaters is a connection string with the following format:
User Id=LoginName;Password=LoginPassword; Enlist=false;Data Source = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = hostname of server)(PORT = Port as configured,default-1521))) (CONNECT_DATA = (SERVICE_NAME=service name as configured,default-orcl)))
where
User ID: The database login account
Password: The password belonging to the login account.
Host: The hostname of the server.
Port: The communication port used to contact the server.
The authors of NServiceBus created a document to explain when and when not to use a certain transport along with the advantages and disadvantages for the various supported transports. This document can be found using the link below.
https://docs.particular.net/transports/selecting
ATS Bus supports the following NServiceBus transports:
RabbitMQ: This is a broker-based queueing solution (https://www.rabbitmq.com/). The broker is installed on a central system (or in the cloud like CloudAMPQ or Amazon MQ). ATS Bus requires a connection string to connect to the broker. The connection string must be in the following format:
host=<hostname>;UserName=<user>;Password=<password>;UseTls=true;CertPath=c:\<cert_directory>\<certname.p12>;CertPassphrase=<cert_password>
Where:
Host: the server where RabbitMQ is installed.
UserName: A user that can access RabbitMQ. See here for more information.
Password: The password of ‘Username’.
UseTLS: A flag indicating if the connection between the bus stop and RabbitMQ should be secured. Visit the RabbitMQ website for details about setting up TLS with RabbitMQ. Visit the Particular website for more information about this item in the connectionstring.
CertPath: The directory and filename of the client certificate, which has the PKCS#12 format.
CertPassphrase: The password that belongs to the client certificate.
ATS Bus uses the conventional routing topology.
The maximum theoretical RabbitMQ message size is 2GB but RabbitMQ does not recommend going beyond 128MB.
Ensure the RabbitMQ server certificate has a SAN extension that holds a DNS entry with the FQDN / hostname of the server that is hosting the RabbitMQ broker. Failing to do so may cause ‘NET::ERR_CERT_COMMON_NAME_INVALID’ errors in the web browser.
Ensure that the Issuer certificate of the RabbitMQ client and server certificate is present in the Trusted Root Certification Authorities folder of the computer that validates the client or server certificate. The certificate validation routines will look for the issuer certificate in this location. Failing to do so may cause ‘NET::ERR_CERT_AUTHORITY_INVALID’ errors in the web browser.
SQL Server: Allows ATS Bus to use SQL Server tables to send/receive/publish messages using SQL Server tables where these tables store and queue messages. The transport requires a connection string to connect to the database.
SQL Server can handle message sizes of 2GB but this is not recommended because the bus stop still needs to serialize/deserialize the message in memory, which affects the memory usage on the system hosting the bus stop.
Please note that this transport does not support native publish-subscribe so an additional table is required to store subscription information. This table is maintained by NServiceBus persistence.
Azure Storage Queues: Allows ATS Bus to exchange messages via Azure using Azure storage queues. More information can be found at https://docs.particular.net/transports/azure-storage-queues/. Setting up Storage Queues requires the user to configure an Azure resource group and a storage account. The connection string required for this transport can be obtained from the ‘Storage account - Access keys’ in the Azure portal.
The Storage Queues in azure are able to store a large amount of messages but the message size is limited to 64KB including headers and body.
Azure Service Bus: Allows ATS Bus to exchange messages via the Azure Service Bus. More information can be found at https://docs.particular.net/transports/azure-service-bus/. Setting up the Azure Service Bus requires the user to configure an Azure resource group and a service bus namespace. The connection string required for this transport can be obtained from the ‘Service Bus Namespace - Shared access policies’ in the Azure portal.
The Azure Service Bus is able to handle 1MB messages.
Configure how often and at which interval messages should be retried when transmission failed. Visit the Particular website for more information.
Immediate retries: How often to immediate retry the message.
Delayed retries: How often to repeat the immediate retries.
Particular ServiceControl receives error, audit, monitoring and control event from the bus stops via 4 separate queues which are configured here.
More information about these queues can be found at https://docs.particular.net/servicecontrol/how.
ServiceControl queue: The bus stop uses this queue to send control messages like subscribing and unsubscribing to specific messages and heartbeat information.
Audit queue: This queue is used to send a copy of a successfully handled message to ServiceControl for auditing.
Error queue: This queue is used to send failed messages to ServiceControl so they can be retried before the retention time expires.
Monitoring queue: This queue is used to send monitoring information to the Particular Monitoring instance. Monitoring information includes message load, queue load etc.
More about monitoring can be found at https://docs.particular.net/servicecontrol/monitoring-instances/
Ensure that ServiceControl is configured to use the same transport as is defined by ‘NServiceBus transport’. ATS Bus is not configured to support multiple transports.
ATS Bus allows OT, IT, ADOS and Cloud bus stops to override the default NServiceBus Recoverability settings. It also allows plug-ins to be enabled. Each bus stop contains an NServiceBus configuration section.
Configure NServiceBus for individual bus stops
Enable heartbeat plug-in: Every 10 seconds, the bus stop will send heartbeat messages to ServiceControl once this feature is enabled. ServiceControl will keep track of these heartbeats and mark a bus stop as active if it receives them on a regular interval and will mark it as inactive if it doesn’t. ServicePulse, the NServiceBus monitoring tool, shows the active/inactive state of the bus stops. This feature is enabled by default when creating a new bus stop, it may be disabled but it is recommended to keep it enabled to allow monitor the active/inactive state of a bus stop.
More information about heartbeats can be found online here and here.
Enable metrics/monitoring: Allows bus stop throughput, processing times and other KPI’s to be monitored in Particular ServicePulse. It shows how well the bus stop is performing.
Enable message auditing: Auditing has a considerable impact on the performance of the monitoring node and the required disk space. Messages not being audited are not shown in ServiceInsight and are not stored in the ServiceControl persistence.
Enable saga auditing: This plug-in enables the Saga view in ServiceInsight. Sagas are containers that can be used by various handlers to add information. Sagas are used for long running operations such as work orders. More information about the plug-in can be found on:
More information about sagas can be found online here.
Immediate retries: How often to immediately retry the message. Remove the tick to override the default value.
Delayed retries: How often to repeat the immediate retries. Remove the tick to override the default value.
Persistence: Configure the bus stop persistence by providing the persistence type and connection string. Remove the tick to override the default value. Not all bus stops have access to a shared persister and therefore the bus stop allows to override the shared persister and configure one specific for the bus stop.
Specify which messages should not be audited by adding them to the Message Auditing Filter (available only for OT Bus Stop).
Can we improve this topic?