Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Samples

Audit Instance Configuration Settings

Component: ServiceControl
Version: 5.x

The configuration of a ServiceControl Audit instance is controlled by the ServiceControl.Audit.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.Audit/InstanceName

Added in version 5.5.0

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

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

ServiceControl.Audit/HostName

The hostname to bind the embedded HTTP API server to; modify this setting to bind to a specific hostname, eg. 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_AUDIT_HOSTNAME
App config keyServiceControl.Audit/HostName
SCMU fieldHOST NAME
TypeDefault value
stringlocalhost

ServiceControl.Audit/Port

The port to bind the embedded HTTP API server.

ContextName
Environment variableSERVICECONTROL_AUDIT_PORT
App config keyServiceControl.Audit/Port
SCMU fieldPORT NUMBER
TypeDefault value
int44444

ServiceControl.Audit/DatabaseMaintenancePort

The port to expose the RavenDB database.

ContextName
Environment variableSERVICECONTROL_AUDIT_DATABASEMAINTENANCEPORT
App config keyServiceControl.Audit/DatabaseMaintenancePort
SCMU fieldDATABASE MAINTENANCE PORT NUMBER (1 - 49151)
TypeDefault value
int44445

ServiceControl.Audit/VirtualDirectory

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

ContextName
Environment variableSERVICECONTROL_AUDIT_VIRTUALDIRECTORY
App config keyServiceControl.Audit/VirtualDirectory
SCMU fieldN/A
TypeDefault value
stringNone

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.

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

ServiceControl.Audit/RavenDBLogLevel

Controls the LogLevel of the RavenDB logs.

ContextName
Environment variableSERVICECONTROL_AUDIT_RAVENDBLOGLEVEL
App config keyServiceControl.Audit/RavenDBLogLevel
SCMU fieldN/A
TypeDefault value
stringOperations

Valid settings are: None, Information, Operations.

Logging

ServiceControl.Audit/LogPath

The path for the ServiceControl logs.

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

ServiceControl.Audit/LogLevel

Controls the LogLevel of the ServiceControl logs.

ContextName
Environment variableSERVICECONTROL_AUDIT_LOGLEVEL
App config keyServiceControl.Audit/LogLevel
SCMU fieldN/A
TypeDefault value
stringInfo

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.

ContextName
Environment variableSERVICECONTROL_AUDIT_TIMETORESTARTAUDITINGESTIONAFTERFAILURE
App config keyServiceControl.Audit/TimeToRestartAuditIngestionAfterFailure
SCMU fieldN/A
TypeDefault value
timespan60 seconds

Valid settings are between 5 seconds and 1 hour.

ServiceControl/IngestAuditMessages

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

ContextName
Environment variableSERVICECONTROL_INGESTAUDITMESSAGES
App config keyServiceControl/IngestAuditMessages
SCMU fieldN/A
TypeDefault value
booltrue

Data retention

ServiceControl.Audit/ExpirationProcessTimerInSeconds

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

ContextName
Environment variableSERVICECONTROL_AUDIT_EXPIRATIONPROCESSTIMERINSECONDS
App config keyServiceControl.Audit/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.Audit/AuditRetentionPeriod

The grace period to keep an audit message before it is deleted.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUDITRETENTIONPERIOD
App config keyServiceControl.Audit/AuditRetentionPeriod
SCMU fieldAUDIT RETENTION PERIOD
TypeDefault value
timespanNone (required)

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

Performance tuning

ServiceControl.Audit/MaxBodySizeToStore

This setting specifies the upper limit on body size, in bytes, to be configured.

ContextName
Environment variableSERVICECONTROL_AUDIT_MAXBODYSIZETOSTORE
App config keyServiceControl.Audit/MaxBodySizeToStore
SCMU fieldN/A
TypeDefault value
int102400 (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.

ContextName
Environment variableSERVICECONTROL_AUDIT_MAXIMUMCONCURRENCYLEVEL
App config keyServiceControl.Audit/MaximumConcurrencyLevel
SCMU fieldN/A
TypeDefault value
int32 in 4.12.0
10 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.

ContextName
Environment variableSERVICECONTROL_AUDIT_ENABLEFULLTEXTSEARCHONBODIES
App config keyServiceControl.Audit/EnableFullTextSearchOnBodies
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/BulkInsertCommitTimeoutInSeconds

Configures the maximum duration, in seconds, for processing a batch of audited messages.

ContextName
Environment variableSERVICECONTROL_AUDIT_BULKINSERTCOMMITTIMEOUTINSECONDS
App config keyServiceControl.Audit/BulkInsertCommitTimeoutInSeconds
SCMU fieldN/A
TypeDefault value
int60 (1 minute)

Transport

ServiceControl.Audit/TransportType

The transport type to run ServiceControl with.

ContextName
Environment variableSERVICECONTROL_AUDIT_TRANSPORTTYPE or TRANSPORTTYPE
App config keyServiceControl.Audit/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_AUDIT_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/AuditQueue

The name of the audit queue to ingest messages from.

ContextName
Environment variableSERVICEBUS_AUDITQUEUE
App config keyServiceBus/AuditQueue
SCMU fieldAUDIT QUEUE NAME
TypeDefault value
stringaudit

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/AuditLogQueue

ContextName
Environment variableSERVICECONTROL_AUDIT_FORWARDAUDITMESSAGES
App config keyServiceControl.Audit/ForwardAuditMessages
SCMU fieldForward audit messages?
TypeDefault value
boolfalse (Off)

ServiceBus/AuditLogQueue

The audit queue name to use for forwarding audit messages. This setting is ignored unless ServiceControl.Audit/ForwardAuditMessages is enabled.

ContextName
Environment variableSERVICEBUS_AUDITLOGQUEUE
App config keyServiceBus/AuditLogQueue
SCMU fieldAUDIT FORWARDING QUEUE NAME
TypeDefault value
string<AuditQueue>.log

ServiceControl.Audit/ServiceControlQueueAddress

The ServiceControl queue name to use for plugin messages (e.g. Heartbeats, Custom Checks, Saga Audit, etc ).

ContextName
Environment variableSERVICECONTROL_AUDIT_SERVICECONTROLQUEUEADDRESS
App config keyServiceControl.Audit/ServiceControlQueueAddress
SCMU fieldN/A
TypeDefault value
stringEmpty

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.

TypeDefault value
int20

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.

TypeDefault value
int5