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.
The configuration of a ServiceControl Error instance is controlled by the ServiceControl.
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
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/InstanceName
Added in version 5.5.0
The name to be used by the error instance and the name of the input queue.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_INSTANCENAME |
App config key | ServiceControl/ |
SCMU field | Instance/Queue Name |
Type | Default value |
---|---|
string | Particular. |
In versions prior to 5.5.0, the InternalQueueName
setting can be used instead.
ServiceControl/HostName
The hostname to bind the embedded HTTP API server to; modify this setting to bind to a specific hostname, e.g. sc.
and make the machine remotely accessible.
This field can also contain a *
as a wildcard to allow remote connections that use any hostname.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_HOSTNAME |
App config key | ServiceControl/ |
SCMU field | HOST NAME |
Type | Default value |
---|---|
string | localhost |
If the ServiceControl/
setting is changed, and the ServiceControl/
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 API server.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_PORT |
App config key | ServiceControl/ |
SCMU field | PORT NUMBER |
Type | Default value |
---|---|
int | 33333 |
If the ServiceControl/
setting is changed, and the ServiceControl/
setting is not set, the path of the embedded RavenDB is changed. Refer to Customize RavenDB Embedded Location.
ServiceControl/DatabaseMaintenancePort
The port to expose the RavenDB database.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_DATABASEMAINTENANCEPORT |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
int | 33334 |
This setting is not relevant when running an error instance in a container.
ServiceControl/VirtualDirectory
The virtual directory to bind the embedded HTTP server to; modify this setting to bind to a specific virtual directory.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_VIRTUALDIRECTORY |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
string | None |
ServiceControl/RemoteInstances
A configuration that specifies one or more attached Audit instances. See also ServiceControl Remote Instances.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_REMOTEINSTANCES |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
string | None |
Embedded database
These settings are not valid for ServiceControl instances hosted in a container.
ServiceControl/DbPath
The path where the internal RavenDB is located.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_AUDIT_DBPATH |
App config key | ServiceControl. |
SCMU field | Database Path |
Type | Default value |
---|---|
string | %SYSTEMDRIVE%\ |
This setting is not relevant when running an error instance in a container.
ServiceControl/RavenDBLogLevel
Controls the LogLevel of the RavenDB logs. See Logging.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_RAVENDBLOGLEVEL |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
string | Operations |
Valid settings are: None
, Information
, Operations
.
Logging
ServiceControl/LogPath
The path for the ServiceControl logs.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_LOGPATH |
App config key | ServiceControl/ |
SCMU field | LOG PATH |
Type | Default value |
---|---|
string | %LOCALAPPDATA%\ |
%LOCALAPPDATA% is a user-specific path on Windows.
When hosted on containers, logs are sent to stdout and this setting is ignored.
ServiceControl/LogLevel
Controls the LogLevel of the ServiceControl logs.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_LOGLEVEL |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
string | Info |
Recoverability
ServiceControl/TimeToRestartErrorIngestionAfterFailure
Controls the maximum time delay to wait before restarting the error ingestion pipeline after detecting a connection problem.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_TIMETORESTARTAUDITINGESTIONAFTERFAILURE |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
timespan | 60 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.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_INGESTERRORMESSAGES |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
bool | true |
Data retention
ServiceControl/ExpirationProcessTimerInSeconds
The number of seconds to wait between checking for expired messages.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_EXPIRATIONPROCESSTIMERINSECONDS |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
int | 600 (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
.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_ERRORRETENTIONPERIOD |
App config key | ServiceControl/ |
SCMU field | ERROR RETENTION PERIOD |
Type | Default value |
---|---|
timespan | None (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.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_EVENTRETENTIONPERIOD |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
timespan | 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.
The maximum concurrency level should be incremented only if there are no verified bottlenecks in CPU, RAM, network I/O, storage I/O, and storage index lag.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_MAXIMUMCONCURRENCYLEVEL |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
int | 10 |
ServiceControl/EnableFullTextSearchOnBodies
Use this setting to configure whether the bodies of processed error messages should be full-text indexed for searching.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_ENABLEFULLTEXTSEARCHONBODIES |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
bool | true |
Changing the full-text search setting will cause indexes to be redeployed and rebuilt. Depending on the number of documents stored, this operation might take a long time and search results won't be available until completed.
Transport
ServiceControl/TransportType
The transport type to run ServiceControl with.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_TRANSPORTTYPE or TRANSPORTTYPE |
App config key | ServiceControl/ |
SCMU field | TRANSPORT |
Type | Default value |
---|---|
string | MSMQ |
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.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_CONNECTIONSTRING or CONNECTIONSTRING |
App config key | NServiceBus/ in connectionStrings |
SCMU field | TRANSPORT CONNECTION STRING |
Type | Default value |
---|---|
string | None |
Valid values are documented in the ServiceControl transport configuration documentation.
ServiceBus/ErrorQueue
The name of the error queue to ingest messages from.
Context | Name |
---|---|
Environment variable | SERVICEBUS_ERRORQUEUE |
App config key | ServiceBus/ |
SCMU field | ERROR QUEUE NAME |
Type | Default value |
---|---|
string | error |
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/
.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_FORWARDERRORMESSAGES |
App config key | ServiceControl/ |
SCMU field | ERROR FORWARDING |
Type | Default value |
---|---|
bool | false (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/
is enabled.
Context | Name |
---|---|
Environment variable | SERVICEBUS_ERRORLOGQUEUE |
App config key | ServiceBus/ |
SCMU field | ERROR FORWARDING QUEUE NAME |
Type | Default value |
---|---|
string |
|
Changing the configuration file or environment value directly will not result in the queue being created. If you are using the ServiceControl Management utility to manage your ServiceControl error instance changing the value will create the forwarding queue if it has not been created.
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/
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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_SERVICECONTROLTHROUGHPUTDATAQUEUE |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | ServiceControl. |
Usage Reporting when using the Azure Service Bus transport
LicensingComponent/ASB/ServiceBusName
Version: 5.4.0+
The Azure ServiceBus name.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_SERVICEBUSNAME |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained from ServiceControl |
LicensingComponent/ASB/TenantId
Version: 5.4.0+
The Azure Tenant ID.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_TENANTID |
App config key | LicensingComponent/ |
Type | Required |
---|---|
string | yes |
LicensingComponent/ASB/SubscriptionId
Version: 5.4.0+
The Azure subscription ID.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_SUBSCRIPTIONID |
App config key | LicensingComponent/ |
Type | Required |
---|---|
string | yes |
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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_CLIENTID |
App config key | LicensingComponent/ |
Type | Required |
---|---|
string | yes |
Example Client ID from an Azure 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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_CLIENTSECRET |
App config key | LicensingComponent/ |
Type | Required |
---|---|
string | yes |
Certificates and federated credentials are not supported at this time.
LicensingComponent/ASB/ManagementUrl
Version: 5.4.0+
The Azure ManagementUrl URL.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_ASB_MANAGEMENTURL |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | https://management.azure.com/ |
This setting only needs to be configured if not using the public AzureCloud environment. For other environments:
- AzureGermanCloud - https://management.microsoftazure.de/
- AzureUSGovernment - https://management.usgovcloudapi.net/
- AzureChinaCloud - https://management.chinacloudapi.cn/
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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_AMAZONSQS_ACCESSKEY |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained 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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_AMAZONSQS_SECRETKEY |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained 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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_AMAZONSQS_PROFILE |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string |
LicensingComponent/AmazonSQS/Region
Version: 5.4.0+
The AWS region to use when accessing AWS services.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_AMAZONSQS_REGION |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained 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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_AMAZONSQS_PREFIX |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained from ServiceControl |
Usage Reporting when using the RabbitMQ transport
LicensingComponent/RabbitMQ/ApiUrl
Version: 5.4.0+
The RabbitMQ management URL.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_RABBITMQ_APIURL |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained from ServiceControl |
LicensingComponent/RabbitMQ/UserName
Version: 5.4.0+
The username to access the RabbitMQ management interface.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_RABBITMQ_USERNAME |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained from ServiceControl |
LicensingComponent/RabbitMQ/Password
Version: 5.4.0+
The password to access the RabbitMQ management interface.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_RABBITMQ_PASSWORD |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained 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.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_SQLSERVER_CONNECTIONSTRING |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
string | obtained from ServiceControl |
LicensingComponent/SqlServer/AdditionalCatalogs
Version: 5.4.0+
Specifies any additional databases on the same server that also contain NServiceBus message queues.
Context | Name |
---|---|
Environment variable | LICENSINGCOMPONENT_SQLSERVER_ADDITIONALCATALOGS |
App config key | LicensingComponent/ |
Type | Default value |
---|---|
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)
Context | Name |
---|---|
Environment variable | SERVICECONTROL_HEARTBEATGRACEPERIOD |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
timespan | 00:00:40 (40 secs) |
When configuring the heartbeat grace period, make sure it is greater than the heartbeat interval defined by the plugin.
When monitoring multiple endpoints, ensure that the heartbeat grace period is larger than any individual heartbeat interval set by the endpoints.
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.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_DATASPACEREMAININGTHRESHOLD |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
int | 20 (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.
Context | Name |
---|---|
Environment variable | SERVICECONTROL_MINIMUMSTORAGELEFTREQUIREDFORINGESTION |
App config key | ServiceControl/ |
SCMU field | N/A |
Type | Default value |
---|---|
int | 5 (percent) |