Measuring system throughput

The Particular throughput tool can be installed locally and run against a production system to discover the throughput of each endpoint in a system over a period of time, which can then be extrapolated to daily throughput numbers.

The tool currently supports collecting data from ServiceControl performance metrics normally displayed in ServicePulse, or by directly interrogating the message transport when using the Azure Service Bus, RabbitMQ, or SQL Sever transports.

The ServiceControl collection method is preferred as ServiceControl already understands what queues comprise an NServiceBus message endpoint.

Installation

To install the tool:

1. Install either .NET Core 3.1 or .NET 6.0.
2. From a terminal window, use the following command to install the throughput counter from MyGet:

   dotnet tool install -g Particular.EndpointThroughputCounter --add-source=https://www.myget.org/F/particular/api/v3/index.json
   

Updating

To update the tool to the latest version, execute the following command in a terminal window:

dotnet tool update -g Particular.ThroughputTool --add-source https://www.myget.org/F/particular/api/v3/index.json

Uninstalling

To uninstall the tool, execute the following command in a terminal window:

dotnet tool uninstall -g Particular.EndpointThroughputCounter

Selecting data collection method

First, determine which method of data collection to use:

• (Preferred) ServiceControl data collection: Use when the system employs monitoring performance metrics in ServicePulse and all endpoints have the monitoring plug-in installed.
• Azure Service Bus:: Use for Azure Service Bus systems.
• RabbitMQ: Use for RabbitMQ systems when ServiceControl is unavailable.
• SQL Transport: Use for SQL transport systems when ServiceControl is unavailable.

Run using ServiceControl data

Once installed, execute the tool with the URLs for the ServiceControl and monitoring APIs, as in this example:

throughput-counter servicecontrol --serviceControlApiUrl http://localhost:33333/api/ --monitoringApiUrl http://localhost:33633/

Because ServiceControl contains, at maximum, the previous 1 hour of monitoring data, the tool will query the ServiceControl API 24 times with a one-hour sleep period between each attempt in order to capture a total of 24 hours worth of data.

Options

All options are required:

Option	Description
--serviceControlApiUrl	The URL of the ServiceControl API. In the ServiceControl Management Utility, find the instance identified as a ServiceControl Instance and use the value of the URL field, as shown in the screenshot below.
--monitoringApiUrl	The URL of the Monitoring API. In the ServiceControl Management Utility, find the instance identified as a Monitoring Instance and use the value of the URL field, as shown in the screenshot below.

This screenshot shows how to identify the instance types and locate the required URLs:

Run using Azure Service Bus

Collecting metrics from Azure Service Bus relies upon the Azure Command Line Interface (CLI), which must be installed first.

1. Install a version of Powershell or Powershell Core on the host system, if not already available.
2. Install the Azure CLI.
3. From a command line, execute az login, which will open a browser to complete the authentication to Azure. The Azure login must have access to view metrics data for the Azure Service Bus namespace.
4. Execute az set --subscription {SubscriptionId}, where {SubscriptionId} is a Guid matching the subscription id that contains the Azure Service Bus namespace.
5. In the Azure Portal, go to the Azure Service Bus namespace, click Properties in the side navigtation (as shown in the screenshot below) and then copy the Id value, which will be needed to run the tool. The Id value should have a format similar to /subscriptions/{Guid}/resourceGroups/{rsrcGroupName}/providers/Microsoft.ServiceBus/namespaces/{namespaceName}.

This screenshot shows how to copy the Service Bus Namespace's Id value:

Once these prerequisites are complete, execute the tool with the resource id of the Azure Service Bus namespace, as in this example:

throughput-counter azureservicebus --resourceId /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/my-resource-group/providers/Microsoft.ServiceBus/namespaces/my-asb-namespace

The tool may open additional terminal windows, which are Powershell processes gathering the data from the Azure CLI.

Unlike ServiceControl, using Azure Service Bus metrics allows the tool to capture the last 30 days worth of data at once, which means that the report will be generated without delay. Although the tool collects 30 days worth of data, only the highest daily throughput is included in the report.

Options

All options are required:

Option	Description
--resourceId	The resource ID of the Azure Service Bus namespace, which can be found in the Azure Portal as described above.

Run using RabbitMQ

To collect data from RabbitMQ, the management plugin must be enabled on the RabbitMQ broker. The tool will also require a login that can access the management UI.

Execute the tool with the RabbitMQ management URL, as in this example where the RabbitMQ broker is running on localhost:

throughput-counter rabbitmq --apiUrl http://localhost:15672

The tool will prompt for the username and password to access the RabbitMQ management interface. After that, it will take its initial reading, then sleep for 24 hours before taking its final reading and generating a report.

Options

All options are required:

Option	Description
--apiUrl	The URL for the RabbitMQ management site.

Run using SQL Transport

Once installed, execute the tool with the database connection string used by SQL Server endpoints, as in this example:

throughput-counter sqlserver --connectionString "Server=SERVER;Database=DATABASE;User=USERNAME;Password=PASSWORD;"

The tool will run for slightly longer than 24 hours in order to capture a beginning and ending RowVersion value for each queue table. A value can only be detected when a message is waiting in the queue to be processed, and not from an empty queue, so the tool may execute multiple SQL queries for each table. The tool will use a backoff mechanism to avoid putting undue pressure on the SQL Server instance.

Options

All options are required:

Option	Description
--connectionString	The database connection string that will provide at least read access to all queue tables.

Masking private data

The report that is generated will contain the names of endpoints/queues. If the queue names themselves contain confidential or proprietary information, certain strings can be masked in the report file.

throughput-counter <command> <options> --queueNameMasks Samples

This will result in a report file with masked data, such as:

{
    "QueueName": "***.RabbitMQ.SimpleReceiver",
    "Throughput": 0
}