The configuration of a ServiceControl Audit 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.
Configuration settings in the application configuration file are applicable to the appSettings section unless otherwise specified.
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.
Changing the host name or port number of an existing ServiceControl Audit instance will break the link from the ServiceControl Error instance. See Moving a remote instance for guidelines on changing these settings.
ServiceControl.Audit/InstanceName
Added in version 5.5.0
The name to be used by the audit instance and the name of the input queue.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_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.Audit/HostName
The hostname to bind the embedded HTTP API server to; modify this setting to bind to a specific hostname, eg. 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_AUDIT_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.Audit/Port
The port to bind the embedded HTTP API server.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_PORT |
| App config key | ServiceControl. |
| SCMU field | PORT NUMBER |
| Type | Default value |
|---|---|
| int | 44444 |
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.Audit/DatabaseMaintenancePort
The port to expose the RavenDB database.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_DATABASEMAINTENANCEPORT |
| App config key | ServiceControl. |
| SCMU field | DATABASE MAINTENANCE PORT NUMBER (1 - 49151) |
| Type | Default value |
|---|---|
| int | 44445 |
This setting is not relevant when running an audit instance in a container.
ServiceControl.Audit/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_AUDIT_VIRTUALDIRECTORY |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| string | None |
ServiceControl.Audit/ShutdownTimeout
Added in version 6.5.0
The maximum allowed time for the process to gracefully complete the shutdown after which the process will try to terminate.
An ungraceful shutdown could result in the next start to require a lengthy database recovery operation.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_SHUTDOWNTIMEOUT |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Environment/Installation type | Type | Default value | | Containers | TimeSpan | 00:00:05 (5 seconds) | | Installation via PowerShell (on Windows) | TimeSpan | 00:02:00 (2 minutes) | | Installation via ServiceControl Management Utility (SCMU) (on Windows) | TimeSpan | 00:02:00 (2 minutes) |
Embedded database
These settings are not valid for ServiceControl instances hosted in a container.
ServiceControl.Audit/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 the audit instance is deployed using a container.
ServiceControl.Audit/RavenDBLogLevel
Controls the LogLevel of the RavenDB logs.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_RAVENDBLOGLEVEL |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| string | Operations |
Valid settings are: None, Information, Operations.
Logging
ServiceControl.Audit/LogPath
The path for the ServiceControl logs.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_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.Audit/LogLevel
Controls the LogLevel of the ServiceControl logs.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_LOGLEVEL |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| string | Info |
Valid settings are: Trace, Debug, Info, Warn, Error, Fatal, Off.
Recoverability
ServiceControl.Audit/TimeToRestartAuditIngestionAfterFailure
Controls the maximum time delay to wait before restarting the audit ingestion pipeline after detecting a connection problem.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_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.Audit/IngestAuditMessages
Set to false to disable ingesting new audit messages. Useful in some upgrade scenarios.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_INGESTAUDITMESSAGES |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| bool | true |
ServiceControl/IngestAuditMessages
This is the same setting as ServiceControl. but kept for backward compatibility
Set to false to disable ingesting new audit messages. Useful in some upgrade scenarios.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_INGESTAUDITMESSAGES |
| App config key | ServiceControl/ |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| bool | true |
Data retention
ServiceControl.Audit/ExpirationProcessTimerInSeconds
The number of seconds to wait between checking for expired messages.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_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.Audit/AuditRetentionPeriod
The grace period to keep an audit message before it is deleted.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_AUDITRETENTIONPERIOD |
| App config key | ServiceControl. |
| SCMU field | AUDIT RETENTION PERIOD |
| Type | Default value |
|---|---|
| timespan | None (required) |
Valid range for this setting is from 1 hour to 365 days.
Starting with version 4.26.0, new audit instances using RavenDB 5 will use the built-in RavenDB expiration process. Changing the audit retention setting will affect only newly ingested messages. Already ingested messages will expire according to the previous retention setting value.
Performance tuning
ServiceControl.Audit/MaxBodySizeToStore
This setting specifies the upper limit on body size, in bytes, to be configured.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_MAXBODYSIZETOSTORE |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| int | 102400 (100Kb) |
ServiceControl.Audit/MaximumConcurrencyLevel
The maximum number of messages that can be concurrently pulled from the message transport.
It is important that the maximum concurrency level be incremented only if there are no verified bottlenecks in CPU, RAM, network I/O, storage I/O, and storage index lag. Higher numbers can result in faster audit message ingestion, but also consume more server resources, and can increase costs in the case of cloud transports that have associated per-operation costs. 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.
Cloud transports with higher latency can benefit from higher concurrency values, but costs can increase as well. Local transports using fast local SSD drives and low latency do not benefit as much.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_MAXIMUMCONCURRENCYLEVEL |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| int | 32 in 4.12.010 in earlier versions |
ServiceControl.Audit/EnableFullTextSearchOnBodies
Added in 4.17.0
Use this setting to configure whether the bodies of processed messages should be full-text indexed for searching.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_ENABLEFULLTEXTSEARCHONBODIES |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| bool | true |
If the audit instance uses RavenDB 5 persistence (available starting 4.26.0), 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.
ServiceControl.Audit/BulkInsertCommitTimeoutInSeconds
Configures the maximum duration, in seconds, for processing a batch of audited messages.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_BULKINSERTCOMMITTIMEOUTINSECONDS |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| int | 60 (1 minute) |
Transport
ServiceControl.Audit/TransportType
The transport type to run ServiceControl with.
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_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_AUDIT_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/AuditQueue
The name of the audit queue to ingest messages from.
| Context | Name |
|---|---|
| Environment variable | SERVICEBUS_AUDITQUEUE |
| App config key | ServiceBus/ |
| SCMU field | AUDIT QUEUE NAME |
| Type | Default value |
|---|---|
| string | audit |
ServiceControl.Audit/ForwardAuditMessages
Use this setting to configure whether processed audit 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_AUDIT_FORWARDAUDITMESSAGES |
| App config key | ServiceControl. |
| SCMU field | Forward audit messages? |
| Type | Default value |
|---|---|
| bool | false (Off) |
ServiceBus/AuditLogQueue
The audit queue name to use for forwarding audit messages. This setting is ignored unless ServiceControl. is enabled.
| Context | Name |
|---|---|
| Environment variable | SERVICEBUS_AUDITLOGQUEUE |
| App config key | ServiceBus/ |
| SCMU field | AUDIT 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 audit instance changing the value will create the forwarding queue if it has not been created.
ServiceControl.Audit/ServiceControlQueueAddress
The ServiceControl queue name to use for plugin messages (e.g. Heartbeats, Custom Checks, Saga Audit, etc ).
| Context | Name |
|---|---|
| Environment variable | SERVICECONTROL_AUDIT_SERVICECONTROLQUEUEADDRESS |
| App config key | ServiceControl. |
| SCMU field | N/A |
| Type | Default value |
|---|---|
| string | Empty |
Troubleshooting
ServiceControl.Audit/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 | Default value |
|---|---|
| int | 20 |
ServiceControl.Audit/MinimumStorageLeftRequiredForIngestion
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 | Default value |
|---|---|
| int | 5 |