Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

Error Instance 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.

The configuration of a ServiceControl Error instance is controlled by the ServiceControl.exe.config file or by setting environment variables. When a setting configuration exists as both an environment variable and in the application configuration file the environment variable setting takes precedence.

Deployments using the ServiceControl Management utility (SCMU) can use that application to make a subset of configuration settings which are read from and written to the application configuration file.

Locating the configuration file using SCMU

image

Host settings

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

ServiceControl/InstanceName

Added in version 5.5.0

The name to be used by the error instance and the name of the input queue.

ContextName
Environment variableSERVICECONTROL_INSTANCENAME
App config keyServiceControl/InstanceName
SCMU fieldInstance/Queue Name
TypeDefault value
stringParticular.ServiceControl

ServiceControl/HostName

The hostname to bind the embedded HTTP API 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.

ContextName
Environment variableSERVICECONTROL_HOSTNAME
App config keyServiceControl/HostName
SCMU fieldHOST NAME
TypeDefault value
stringlocalhost

ServiceControl/Port

The port to bind the embedded HTTP API server.

ContextName
Environment variableSERVICECONTROL_PORT
App config keyServiceControl/Port
SCMU fieldPORT NUMBER
TypeDefault value
int33333

ServiceControl/DatabaseMaintenancePort

The port to expose the RavenDB database.

ContextName
Environment variableSERVICECONTROL_DATABASEMAINTENANCEPORT
App config keyServiceControl/DatabaseMaintenancePort
SCMU fieldN/A
TypeDefault value
int33334

ServiceControl/VirtualDirectory

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

ContextName
Environment variableSERVICECONTROL_VIRTUALDIRECTORY
App config keyServiceControl/VirtualDirectory
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl/RemoteInstances

A configuration that specifies one or more attached Audit instances. See also ServiceControl Remote Instances.

ContextName
Environment variableSERVICECONTROL_REMOTEINSTANCES
App config keyServiceControl/RemoteInstances
SCMU fieldN/A
TypeDefault value
stringNone

Embedded database

These settings are not valid for ServiceControl instances hosted in a container.

ServiceControl/DbPath

The path where the internal RavenDB is located.

ContextName
Environment variableSERVICECONTROL_AUDIT_DBPATH
App config keyServiceControl.Audit/DbPath
SCMU fieldDatabase Path
TypeDefault value
string%SYSTEMDRIVE%\ProgramData\Particular\ServiceControl\<instance_name>\DB

ServiceControl/RavenDBLogLevel

Controls the LogLevel of the RavenDB logs. See Logging.

ContextName
Environment variableSERVICECONTROL_RAVENDBLOGLEVEL
App config keyServiceControl/RavenDBLogLevel
SCMU fieldN/A
TypeDefault value
stringOperations

Valid settings are: None, Information, Operations.

Logging

ServiceControl/LogPath

The path for the ServiceControl logs.

ContextName
Environment variableSERVICECONTROL_LOGPATH
App config keyServiceControl/LogPath
SCMU fieldLOG PATH
TypeDefault value
string%LOCALAPPDATA%\Particular\ServiceControl\logs

ServiceControl/LogLevel

Controls the LogLevel of the ServiceControl logs.

ContextName
Environment variableSERVICECONTROL_LOGLEVEL
App config keyServiceControl/LogLevel
SCMU fieldN/A
TypeDefault value
stringInfo

Recoverability

ServiceControl/TimeToRestartErrorIngestionAfterFailure

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

ContextName
Environment variableSERVICECONTROL_TIMETORESTARTAUDITINGESTIONAFTERFAILURE
App config keyServiceControl/TimeToRestartAuditIngestionAfterFailure
SCMU fieldN/A
TypeDefault value
timespan60 seconds

Valid settings are between 5 seconds and 1 hour.

ServiceControl/IngestErrorMessages

Version: 4.33.0+

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

ContextName
Environment variableSERVICECONTROL_INGESTERRORMESSAGES
App config keyServiceControl/IngestErrorMessages
SCMU fieldN/A
TypeDefault value
booltrue

Data retention

ServiceControl/ExpirationProcessTimerInSeconds

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

ContextName
Environment variableSERVICECONTROL_EXPIRATIONPROCESSTIMERINSECONDS
App config keyServiceControl/ExpirationProcessTimerInSeconds
SCMU fieldN/A
TypeDefault value
int600 (10 minutes)

Valid range is 0 to 10800 (3 Hours).

Setting the value to 0 will disable the expiration process. This is not recommended and it is only provided for fault finding.

ServiceControl/ErrorRetentionPeriod

The grace period that errored 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.

ContextName
Environment variableSERVICECONTROL_ERRORRETENTIONPERIOD
App config keyServiceControl/ErrorRetentionPeriod
SCMU fieldERROR RETENTION PERIOD
TypeDefault value
timespanNone (required)

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

ServiceControl/EventRetentionPeriod

The grace period to keep event logs before they are deleted.

ContextName
Environment variableSERVICECONTROL_EVENTRETENTIONPERIOD
App config keyServiceControl/EventRetentionPeriod
SCMU fieldN/A
TypeDefault value
timespan14 days

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

ServiceControl/TrackInstancesInitialValue

The default value for whether to Track or Do not Track endpoint instance on newly discovered endpoints.

ContextName
Environment variableSERVICECONTROL_TRACKINSTANCESINITIALVALUE
App config keyServiceControl/TrackInstancesInitialValue
SCMU fieldN/A
TypeDefault value
booltrue (Track)

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.

ContextName
Environment variableSERVICECONTROL_MAXIMUMCONCURRENCYLEVEL
App config keyServiceControl/MaximumConcurrencyLevel
SCMU fieldN/A
TypeDefault value
int10

ServiceControl/EnableFullTextSearchOnBodies

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

ContextName
Environment variableSERVICECONTROL_ENABLEFULLTEXTSEARCHONBODIES
App config keyServiceControl/EnableFullTextSearchOnBodies
SCMU fieldN/A
TypeDefault value
booltrue

Transport

ServiceControl/TransportType

The transport type to run ServiceControl with.

ContextName
Environment variableSERVICECONTROL_TRANSPORTTYPE or TRANSPORTTYPE
App config keyServiceControl/TransportType
SCMU fieldTRANSPORT
TypeDefault value
stringMSMQ

Valid values are documented in the ServiceControl transport configuration documentation.

NServiceBus/Transport

The connection string for the transport. This setting must be entered in the connectionStrings section of the configuration file when configured using the app config.

ContextName
Environment variableSERVICECONTROL_CONNECTIONSTRING or CONNECTIONSTRING
App config keyNServiceBus/Transport in connectionStrings
SCMU fieldTRANSPORT CONNECTION STRING
TypeDefault value
stringNone

Valid values are documented in the ServiceControl transport configuration documentation.

ServiceBus/ErrorQueue

The name of the error queue to ingest messages from.

ContextName
Environment variableSERVICEBUS_ERRORQUEUE
App config keyServiceBus/ErrorQueue
SCMU fieldERROR QUEUE NAME
TypeDefault value
stringerror

ServiceControl/ForwardErrorMessages

Use this setting to configure whether processed error messages are forwarded to another queue or not. This entry should be set to false if there is no external process reading messages from the ServiceBus/ErrorLogQueue.

ContextName
Environment variableSERVICECONTROL_FORWARDERRORMESSAGES
App config keyServiceControl/ForwardErrorMessages
SCMU fieldERROR FORWARDING
TypeDefault value
boolfalse (Off)

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

ServiceBus/ErrorLogQueue

The error queue name to use for forwarding error messages. This setting is ignored unless ServiceControl/ForwardErrorMessages is enabled.

ContextName
Environment variableSERVICEBUS_ERRORLOGQUEUE
App config keyServiceBus/ErrorLogQueue
SCMU fieldERROR FORWARDING QUEUE NAME
TypeDefault value
string<ErrorQueue>.log

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.

ContextName
Environment variableLICENSINGCOMPONENT_SERVICECONTROLTHROUGHPUTDATAQUEUE
App config keyLicensingComponent/ServiceControlThroughputDataQueue
TypeDefault value
stringServiceControl.ThroughputData

Usage Reporting when using the Azure Service Bus transport

LicensingComponent/ASB/ServiceBusName

Version: 5.4.0+

The Azure ServiceBus name.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_SERVICEBUSNAME
App config keyLicensingComponent/ASB/ServiceBusName
TypeDefault value
stringobtained from ServiceControl

LicensingComponent/ASB/TenantId

Version: 5.4.0+

The Azure Tenant ID.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_TENANTID
App config keyLicensingComponent/ASB/TenantId
TypeRequired
stringyes

LicensingComponent/ASB/SubscriptionId

Version: 5.4.0+

The Azure subscription ID.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_SUBSCRIPTIONID
App config keyLicensingComponent/ASB/SubscriptionId
TypeRequired
stringyes

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.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_CLIENTID
App config keyLicensingComponent/ASB/ClientId
TypeRequired
stringyes

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.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_CLIENTSECRET
App config keyLicensingComponent/ASB/ClientSecret
TypeRequired
stringyes

LicensingComponent/ASB/ManagementUrl

Version: 5.4.0+

The Azure ManagementUrl URL.

ContextName
Environment variableLICENSINGCOMPONENT_ASB_MANAGEMENTURL
App config keyLicensingComponent/ASB/ManagementUrl
TypeDefault value
stringhttps://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.

ContextName
Environment variableLICENSINGCOMPONENT_AMAZONSQS_ACCESSKEY
App config keyLicensingComponent/AmazonSQS/AccessKey
TypeDefault value
stringobtained from ServiceControl

LicensingComponent/AmazonSQS/SecretKey

Version: 5.4.0+

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

ContextName
Environment variableLICENSINGCOMPONENT_AMAZONSQS_SECRETKEY
App config keyLicensingComponent/AmazonSQS/SecretKey
TypeDefault value
stringobtained from ServiceControl

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.

ContextName
Environment variableLICENSINGCOMPONENT_AMAZONSQS_PROFILE
App config keyLicensingComponent/AmazonSQS/Profile
TypeDefault value
string

LicensingComponent/AmazonSQS/Region

Version: 5.4.0+

The AWS region to use when accessing AWS services.

ContextName
Environment variableLICENSINGCOMPONENT_AMAZONSQS_REGION
App config keyLicensingComponent/AmazonSQS/Region
TypeDefault value
stringobtained from ServiceControl

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.

ContextName
Environment variableLICENSINGCOMPONENT_AMAZONSQS_PREFIX
App config keyLicensingComponent/AmazonSQS/Prefix
TypeDefault value
stringobtained from ServiceControl

Usage Reporting when using the RabbitMQ transport

LicensingComponent/RabbitMQ/ApiUrl

Version: 5.4.0+

The RabbitMQ management URL.

ContextName
Environment variableLICENSINGCOMPONENT_RABBITMQ_APIURL
App config keyLicensingComponent/RabbitMQ/ApiUrl
TypeDefault value
stringobtained from ServiceControl

LicensingComponent/RabbitMQ/UserName

Version: 5.4.0+

The username to access the RabbitMQ management interface.

ContextName
Environment variableLICENSINGCOMPONENT_RABBITMQ_USERNAME
App config keyLicensingComponent/RabbitMQ/UserName
TypeDefault value
stringobtained from ServiceControl

LicensingComponent/RabbitMQ/Password

Version: 5.4.0+

The password to access the RabbitMQ management interface.

ContextName
Environment variableLICENSINGCOMPONENT_RABBITMQ_PASSWORD
App config keyLicensingComponent/RabbitMQ/Password
TypeDefault value
stringobtained from ServiceControl

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.

ContextName
Environment variableLICENSINGCOMPONENT_SQLSERVER_CONNECTIONSTRING
App config keyLicensingComponent/SqlServer/ConnectionString
TypeDefault value
stringobtained from ServiceControl

LicensingComponent/SqlServer/AdditionalCatalogs

Version: 5.4.0+

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

ContextName
Environment variableLICENSINGCOMPONENT_SQLSERVER_ADDITIONALCATALOGS
App config keyLicensingComponent/SqlServer/AdditionalCatalogs
TypeDefault value
string

Usage Reporting when using the PostgreSQL transport

LicensingComponent/PostgreSQL/ConnectionString

Version: 5.10.0+

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

ContextName
Environment variableLICENSINGCOMPONENT_POSTGRESQL_CONNECTIONSTRING
App config keyLicensingComponent/PostgreSQL/ConnectionString
TypeDefault value
stringobtained from ServiceControl

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)

ContextName
Environment variableSERVICECONTROL_HEARTBEATGRACEPERIOD
App config keyServiceControl/HeartbeatGracePeriod
SCMU fieldN/A
TypeDefault value
timespan00: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/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.

ContextName
Environment variableSERVICECONTROL_DATASPACEREMAININGTHRESHOLD
App config keyServiceControl/DataSpaceRemainingThreshold
SCMU fieldN/A
TypeDefault value
int20 (percent)

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.

ContextName
Environment variableSERVICECONTROL_MINIMUMSTORAGELEFTREQUIREDFORINGESTION
App config keyServiceControl/MinimumStorageLeftRequiredForIngestion
SCMU fieldN/A
TypeDefault value
int5 (percent)