Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
Monitoring
Samples

Configuration Settings

Component: ServiceControl
Version: 5.x

The configuration of a ServiceControl instance can be adjusted via the ServiceControl Management utility or by directly modifying the ServiceControl.exe.config file. The settings listed are applicable to the appSettings section of the configuration file unless otherwise specified.

image

Host settings

The following documents should be reviewed prior to modifying configuration settings:

ServiceControl/HostName

The hostname to bind the embedded HTTP server to; modify this setting to bind to a specific hostname, e.g. sc.mydomain.com and make the machine remotely accessible

This field can also contain a * as a wildcard to allow remote connections that use any hostname.

Type: string

Default: localhost

ServiceControl/Port

The port to bind the embedded HTTP server.

Type: int

Default: 33333.

ServiceControl/DatabaseMaintenancePort

The port to bind the RavenDB when in maintenance mode or RavenDB is exposed.

Type: int

Default: 33334.

ServiceControl/VirtualDirectory

The virtual directory to bind the embedded HTTP server to; modify this setting to bind to a specific virtual directory.

Type: string

Default: empty

ServiceControl/DbPath

The path where the internal RavenDB is located.

Type: string

Default: %SYSTEMDRIVE%\ProgramData\Particular\ServiceControl\<instance_name>\DB

ServiceControl/LogPath

The path for the ServiceControl logs.

Type: string

Default: %LOCALAPPDATA%\Particular\ServiceControl\logs

ServiceControl/LogLevel

Controls the LogLevel of the ServiceControl logs.

Type: string

Default: Info

Valid settings are: Trace, Debug, Info, Warn, Error, Fatal, Off.

This setting will default to Info if an invalid value is assigned.

ServiceControl/RavenDBLogLevel

Controls the LogLevel of the RavenDB logs. See Logging.

Type: string

Default: Operations

Valid settings are: None, Information, Operations.

This setting will default to Warn if an invalid value is assigned.

ServiceControl/TimeToRestartErrorIngestionAfterFailure

Version: 4.4.1+

Controls the maximum time delay to wait before restarting the error ingestion pipeline after detecting a connection problem.

Type: TimeSpan

Default: 60 seconds

Valid settings are between 5 seconds and 1 hour.

ServiceControl/InternalQueueName

Version: 4.27.0+

Controls the name of the internal queue that ServiceControl uses for internal control messages. This can be used when the internal queue name does not match the Windows Service Name.

Type: string

Default: The Service Name

ServiceControl/IngestErrorMessages

Version: 4.33.0+

Set to false to disable ingesting new error messages. Useful in some upgrade scenarios.

Type: bool true or false

Default: true

Data retention

ServiceControl/ExpirationProcessTimerInSeconds

The number of seconds to wait between checking for expired messages.

Type: int

Default: 600 (10 minutes). The default for ServiceControl version 1.3 and below is 60 (1 minute), Starting in version 1.4, the default is 600 (10 minutes). Setting the value to 0 will disable the expiration process. This is not recommended and it is only provided for fault finding. Valid range is 0 to 10800 (3 Hours).

ServiceControl/ErrorRetentionPeriod

The grace period that faulted messages are kept before they are deleted.

For a message to be considered for deletion, it needs to have a status of either Archived, RetryIssued, or Resolved.

Type: timespan

Default: There is no default; this setting is required.

Valid range for this setting is between 5 days and 45 days.

ServiceControl/EventRetentionPeriod

The period to keep event logs before they are deleted.

Type: timespan

Default: 14 (14 days).

Valid range for this setting is from 1 hour to 200 days.

Performance tuning

ServiceControl/MaximumConcurrencyLevel

This setting controls how many messages can be processed concurrently (in parallel) by ServiceControl. The default value is 10.

In some cases, the ingestion rate can be too high and the underlying database cannot keep up with indexing the new messages. In this case, consider lowering the maximum concurrency level to a value that still allows a suitable ingestion rate while easing the pressure on the database.

ServiceControl/HttpDefaultConnectionLimit

The maximum number of concurrent connections allowed by ServiceControl. When working with transports that operate over HTTP, the number of concurrent connections can be increased to meet transport concurrency settings.

Type: string

Default: 100

ServiceControl/EnableFullTextSearchOnBodies

Version: 4.17.0+

Use this setting to configure whether the bodies of processed error messages should be full-text indexed for searching.

Type: bool true or false

Default: true.

Transport

ServiceControl/TransportType

The transport type to run ServiceControl with.

Type: string

Default: ServiceControl.Transports.Msmq.MsmqTransportCustomization, ServiceControl.Transports.Msmq

The assembly containing the transport type needs to be present in the ServiceControl directory for ServiceControl being able to instantiate the transport type.

NServiceBus/Transport

The connection string for the transport. This setting should be placed in the connectionStrings section of the configuration file.

Type: string

ServiceBus/ErrorQueue

The error queue name.

Type: string

Default: error

ServiceBus/ErrorLogQueue

The error queue name to use for forwarding error messages.

Type: string

Default: <ErrorQueue>.log

ServiceControl creates the queue specified by this setting only if ServiceControl/ForwardErrorMessages is enabled.

ServiceControl/ForwardErrorMessages

Use this setting to configure whether processed error messages are forwarded to another queue or not.

Type: bool true or false

Default: There is no default. This setting needs to be specified.

This entry should be set to false if there is no external process reading messages from the Error Forwarding Queue.

See Installation for details on how to set this at install time.

Usage Reporting when using ServiceControl

LicensingComponent/ServiceControlThroughputDataQueue

Version: 5.4.0+

The queue on which throughput data is received by the ServiceControl Error instance. This setting must match the equivalent Monitoring/ServiceControlThroughputDataQueue setting for the Monitoring instance.

In most instances these settings do not need to be modified.

If running multiple setups of the Platform Tools (i.e. multiple versions of ServiceControl error and monitoring instances) then modify these settings so that the queue on each monitoring instance is matched to the queue of its error instance.

If using MSMQ transport and the monitoring instance is installed on a different machine than the ServiceControl error instance, only the monitoring instance setting needs to be modified to include the machine name of the error instance in the queue address.

Type: string

Default: ServiceControl.ThroughputData

Usage Reporting when using the Azure Service Bus transport

LicensingComponent/ASB/TenantId

Version: 5.4.0+

The Azure Tenant ID.

Type: string

LicensingComponent/ASB/SubscriptionId

Version: 5.4.0+

The Azure subscription ID.

Type: string

LicensingComponent/ASB/ClientId

Version: 5.4.0+

The Client ID (aka Application ID) for an Azure service principal that has access to read metrics data for the Azure Service Bus namespace.

Type: string

Example Client ID from an Azure App Registration: Screenshot showing where the Client ID appears in an App Registration

LicensingComponent/ASB/ClientSecret

Version: 5.4.0+

The client secret for an Azure service principal that has access to read metrics data for the Azure Service Bus namespace.

Type: string

LicensingComponent/ASB/ManagementUrl

Version: 5.4.0+

The Azure ManagementUrl URL.

Type: string

Default: https://management.azure.com

This setting only needs to be configured if not using the public AzureCloud environment. For other environments:

Usage Reporting when using the Amazon SQS transport

LicensingComponent/AmazonSQS/AccessKey

Version: 5.4.0+

The AWS Access Key ID to use to discover queue names and gather per-queue metrics.

Type: string

LicensingComponent/AmazonSQS/SecretKey

Version: 5.4.0+

The AWS Secret Access Key to use to discover queue names and gather per-queue metrics.

Type: string

LicensingComponent/AmazonSQS/Profile

Version: 5.4.0+

The name of a local AWS credentials profile to use to discover queue names and gather per-queue metrics.

Type: string

LicensingComponent/AmazonSQS/Region

Version: 5.4.0+

The AWS region to use when accessing AWS services.

Type: string

LicensingComponent/AmazonSQS/Prefix

Version: 5.4.0+

Report only on queues that begin with the specified prefix. This is commonly used when one AWS account must contain queues for multiple projects or multiple environments.

Type: string

Usage Reporting when using the RabbitMQ transport

LicensingComponent/RabbitMQ/ApiUrl

Version: 5.4.0+

The RabbitMQ management URL.

Type: string

LicensingComponent/RabbitMQ/UserName

Version: 5.4.0+

The username to access the RabbitMQ management interface.

Type: string

LicensingComponent/RabbitMQ/Password

Version: 5.4.0+

The password to access the RabbitMQ management interface.

Type: string

Usage Reporting when using the SqlServer transport

LicensingComponent/SqlServer/ConnectionString

Version: 5.4.0+

The connection string that will provide at least read access to all queue tables.

Type: string

LicensingComponent/SqlServer/AdditionalCatalogs

Version: 5.4.0+

Specifies any additional databases on the same server that also contain NServiceBus message queues.

Type: string

Plugin-specific

ServiceControl/HeartbeatGracePeriod

The period that defines whether an endpoint is considered alive or not since the last received heartbeat.

Type: timespan

Default: 00:00:40 (40 secs)

When configuring the heartbeat grace period, make sure it is greater than the heartbeat interval defined by the plugin.

Troubleshooting

ServiceControl/ExposeRavenDB

ServiceControl stores its data in a RavenDB embedded instance. By default, the RavenDB instance is accessible only by the ServiceControl service. If during troubleshooting, direct access to the RavenDB instance is required while ServiceControl is running, ServiceControl can be configured to expose the RavenDB studio.

Type: bool

Default: false

After restarting the ServiceControl service, access the RavenDB studio locally at the following endpoint:

http://localhost:{configured ServiceControl instance maintenance port}/studio/index.html#databases/documents?&database=%3Csystem%3E

ServiceControl/DataSpaceRemainingThreshold

The percentage threshold for the Message database storage space check. If the remaining hard drive space drops below this threshold (as a percentage of the total space on the drive), then the check will fail, alerting the user.

Type: int

Default: 20

ServiceControl/MinimumStorageLeftRequiredForIngestion

This setting was introduced in version 4.28. The percentage threshold for the Critical message database storage space check. If the remaining hard drive space drops below this threshold (as a percentage of the total space on the drive), then the check will fail, alerting the user. The message ingestion will also be stopped to prevent data loss. Message ingestion will resume once more disk space is made available.

Type: int

Default: 5