The configuration of a ServiceControl instance can be adjusted via the ServiceControl Management utility or by directly modifying the ServiceControl. file. The settings listed are applicable to the appSettings section of the configuration file unless otherwise specified.
Host settings
The following documents should be reviewed prior to modifying configuration settings:
- Setting a Custom Hostname for guidance and details.
- Securing ServiceControl for an overview of the security implications of changing the configuration.
ServiceControl/HostName
The hostname to bind the embedded HTTP server to; modify this setting to bind to a specific hostname, e.g. sc..
Type: string
Default: localhost
ServiceControl/HostName setting is changed, and the ServiceControl/DbPath setting is not set, the path of the embedded RavenDB is changed. Refer to Customize RavenDB Embedded Location.ServiceControl/Port
The port to bind the embedded HTTP server.
Type: int
Default: 33333.
ServiceControl/Port setting is changed, and the ServiceControl/DbPath setting is not set, the path of the embedded RavenDB is changed. Refer to Customize RavenDB Embedded Location.ServiceControl/DatabaseMaintenancePort
The port to bind the RavenDB when in maintenance mode or RavenDB is exposed. This setting is only applicable from version 2 and above.
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%\
The indexes and Esent logs can be stored in a different path from the the RavenDB database data files by using the following RavenDB configuration app settings:
Raven/IndexStoragePath
The path for the indexes on disk.
Type: string
Default: %SYSTEMDRIVE%\
Raven/Esent/LogsPath
The path for the Esent logs on disk.
Type: string
Default: %SYSTEMDRIVE%\
ServiceControl/LogPath
The path for the ServiceControl logs.
Type: string
Default: %LOCALAPPDATA%\
ServiceControl/LogLevel
Controls the LogLevel of the ServiceControl logs.
Type: string
Default: Info
In ServiceControl version 1.9 and above, valid settings are: Trace, Debug, Info, Warn, Error, Fatal, Off.
This setting will default to Info if an invalid value is assigned.
In version 1.8 and below, the log level is Info and can not be changed.
ServiceControl/RavenDBLogLevel
Controls the LogLevel of the RavenDB logs. This setting was introduced in ServiceControl version 1.10. See Logging
Type: string
Default: Warn
Valid settings are: Trace, Debug, Info, Warn, Error, Fatal, Off.
This setting will default to Warn if an invalid value is assigned.
ServiceControl/TimeToRestartErrorIngestionAfterFailure
Controls the maximum time delay to wait before restarting the error ingestion pipeline after detecting a connection problem. This setting was introduced in ServiceControl version 4.4.1.
Type: timespan
Default: 60 seconds
Valid settings are between 5 seconds and 1 hour.
ServiceControl/InternalQueueName
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.
This setting was introduced in ServiceControl version 4.27.0.
Type: string
Default: The Service Name
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/ExpirationProcessBatchSize
This setting was introduced in version 1.4. The minimum allowed value for this setting is 10240; there is no hard-coded maximum as this is dependent on system performance.
Type: int
Default: 65512.
ServiceControl/HoursToKeepMessagesBeforeExpiring
This setting is only applicable in version 1.11.1 and below.
In higher versions, this setting can be set via ServiceControl/.
The number of hours to keep a message before it is deleted.
Type: int
Default: 720 (30 days).
In ServiceControl versions, 1.8.2 and below, the valid range for this setting is 24 (1 day) to 1440 (60 days).
Starting in versions 1.8.3, the upper limit has been removed to allow for longer retention. This was done to allow scenarios with low volumes of messages to retain them longer. Setting this value too high can cause the embedded RavenDB to become large and unresponsive when indexing. See Capacity and Planning.
ServiceControl/AuditRetentionPeriod
This setting is only applicable, starting from versions 1.12.
This setting is deprecated in version 4.0.0. See ServiceControl Audit configuration.
The period to keep an audit message before it is deleted.
Type: timespan
Default: There is no default; this setting is required.
Valid range for this setting is from 1 hour to 365 days.
ServiceControl/ErrorRetentionPeriod
This setting is only applicable, starting from version 1.12.
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
This setting is only applicable, starting from version 1.25.
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/MaximumMessageThroughputPerSecond
The setting controls the maximum throughput of messages ServiceControl will handle per second and is necessary to avoid overloading the underlying messages database. An appropriate limit ensures that the database can cope with the anticipated number of insert operations. Otherwise, the query performance would drop significantly, and the message expiration process would stop working when under heavy insert load. Make sure to conduct thorough performance tests on the hardware before increasing this value.
Type: int
Default: 350.
ServiceControl/MaxBodySizeToStore
This setting was introduced in version 1.6. It allows the upper limit on body size to be configured.
In version 1.5.* and below, ServiceControl stores only the bodies of audit messages that are smaller than 100Kb.
Type: int
Default: 102400 (100Kb)
ServiceControl/HttpDefaultConnectionLimit
This setting was introduced in version 1.6.2. 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
This setting is only applicable starting from 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.
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/AuditQueue
This setting is only applicable in versions 3.8.2 and below. See ServiceControl Audit configuration.
The audit queue name.
Type: string
Default: audit
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:
Starting in version 1.29, ServiceControl creates the queue specified by this setting only if ServiceControl/ is enabled. In previous versions, the queue specified by this setting is created when the service instance is installed regardless of the value of ServiceControl/.
ServiceBus/AuditLogQueue
This setting is only applicable in versions 3.8.2 and below. See ServiceControl Audit configuration.
The audit queue name to use for forwarding audit messages. This works only if ServiceControl/ is true.
Type: string
Default:
Starting in version 1.29, ServiceControl creates the queue specified by this setting only if ServiceControl/ is enabled. In previous versions, the queue specified by this setting is created when the service instance is installed regardless of the value of ServiceControl/.
ServiceControl/ForwardAuditMessages
This setting is only applicable in versions 3.8.2 and below. See ServiceControl Audit configuration.
Use this setting to configure whether processed audit messages are forwarded to another queue or not. This queue is known as the Audit Forwarding Queue.
Type: bool true or false
Default: false.
In version 1.5 and above, if this setting is not explicitly set to true or false, a warning is shown in the logs at startup.
In version 1.12.0 and above, there is no default for this setting. This setting needs to be specified.
See Installation for details on how to set this at install time.
ServiceControl/ForwardErrorMessages
This setting is only applicable from version 1.12.0 and above.
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.
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
This setting was introduced in version 3.8. 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