The Particular Service Platform is licensed based on the number of NServiceBus endpoints and the message throughput of those endpoints. In order to determine these values, a monitor needs to be run over the transport broker for a representative period of time (24 hours) and a report generated from this data to be sent to Particular.
The minimal installation required to generate the usage report is:
- ServiceControl. Only a single error instance is required, as this is the primary service that contains the monitoring logic.
- ServicePulse. This is the UI that interfaces with the ServiceControl service to allow users to specify which endpoints are NServiceBus related and generate the usage report to send to Particular.
The following methods can be used to install these requirements:
- Windows Only
- ServiceControl through ServiceControl Management Utility
- ServiceControl through Powershell
- ServicePulse
- Linux or Windows
- ServiceControl and ServicePulse through Containers
Windows Installation
ServiceControl
ServiceControl is installed as a Windows service, and starts automatically. It includes an embedded RavenDB instance that stores all the data required for generating usage reports (and any other functions of ServiceControl that you may use).
ServiceControl Management Utility (SCMU)
- Download the latest SCMU
- Run the executable. This will require Admin priveleges
- Add a new ServiceControl and Audit instance
- Uncheck the
ServiceControl Audit
node, since this isn't required for usage reports - Choose your transport and supply the connection string
By default, the ServiceControl instance will immediately start reading from the error
queue when it starts. If this is not desired, e.g. if you have another process that monitors the error queue, then expand the ServiceControl
node and change the value of Error Queue Name
to a non-existing queue name before clicking 'Add' Alternatively, set the
SERVICECONTROL_INGESTERRORMESSAGES
environment variable to false
before clicking Add
- Click 'Add'
Powershell
- Ensure you meet the prerequisites
- Install and import the Particular.ServiceControl.Management module
- Run the New-ServiceControlInstance cmdlet
- Most of the parameters can be left as per the example, with the
-Transport
and-ConnectionString
parameters set according to your environment.
- Most of the parameters can be left as per the example, with the
By default, the ServiceControl instance will immediately start reading from the error
queue when it starts. If this is not desired, e.g. if you have another process that monitors the error queue, either set the -ErrorQueue
parameter to a non-existing queue name, or set the SERVICECONTROL_INGESTERRORMESSAGES
environment variable to false
before running the cmdlet
ServicePulse
Follow the installation instructions and ensure ServicePulse is configured to point to the port of the ServiceControl instance installed above.
Container Installation
When installing ServiceControl directly, through one of the above solutions, it includes an embedded RavenDB instance that stores all the data required for generating usage reports (and any other functions of ServiceControl that you may use). When using containers, a separate RavenDB database is required. This can also be containerized, allowing for a single docker compose to install all dependencies. An example of this can be found in the Platform Container Examples repository.
The containers required for generating a usage report are:
- RavenDB
- Alternatively another RavenDB source can be used. The connection string must be supplied when installing ServiceControl
- ServiceControl
By default, the ServiceControl instance will immediately start reading from the error
queue when it starts. If this is not desired, e.g. if you have another process that monitors the error queue, then one of the following parameters should be supplied to the docker run
command
- -e SERVICEBUS_ERRORQUEUE=<<name of non-existing queue, e.g.
errornotused
>> - -e SERVICECONTROL_INGESTERRORMESSAGES=false
Cloud
When hosting containers in the cloud, it is suggested to use RavenDB Cloud to host the database. This is because the storage requirements of RavenDB generally cannot be met on most cloud offerings.