Getting Started
Architecture
NServiceBus
Transports
Persistence
ServiceInsight
ServicePulse
ServiceControl
Monitoring
Modernization
Samples

Audit Instance Configuration Settings

Component: ServiceControl
Version: 4.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

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.

ContextName
Environment variableSERVICECONTROL_AUDIT_SHUTDOWNTIMEOUT
App config keyServiceControl.Audit/ShutdownTimeout
SCMU fieldN/A
Environment/Installation typeTypeDefault value
ContainersTimeSpan00:00:05 (5 seconds)
Installation via PowerShell (on Windows)TimeSpan00:02:00 (2 minutes)
Installation via ServiceControl Management Utility (SCMU) (on Windows)TimeSpan00:02:00 (2 minutes)

ServiceControl.Audit/MaintenanceMode

Run ServiceControl audit instance in maintenance mode in order to do database maintenance.

ContextName
Environment variableSERVICECONTROL_AUDIT_MAINTENANCEMODE
App config keyServiceControl.Audit/MaintenanceMode
SCMU fieldN/A
TypeDefault value
booleanFalse

Authentication

These settings configure authentication using OAuth 2.0 and OpenID Connect. Refer to the hosting and security guide, or authentication configuration examples for additional information.

ServiceControl.Audit/Authentication.Enabled

Added in version 6.11.0

Enables or disables authentication. This is a Global switch and all other authentication settings are ignored unless this is true.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_ENABLED
App config keyServiceControl.Audit/Authentication.Enabled
SCMU fieldN/A
TypeDefault value
boolfalse

ServiceControl.Audit/Authentication.Authority

Added in version 6.11.0

The URL of the OpenID Connect authority (identity provider) used to authenticate tokens.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_AUTHORITY
App config keyServiceControl.Audit/Authentication.Authority
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl.Audit/Authentication.Audience

Added in version 6.11.0

The expected audience value in the JWT token, typically the application ID or URI of the API.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_AUDIENCE
App config keyServiceControl.Audit/Authentication.Audience
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl.Audit/Authentication.ValidateIssuer

Added in version 6.11.0

Controls whether the token issuer is validated against the authority.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEISSUER
App config keyServiceControl.Audit/Authentication.ValidateIssuer
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/Authentication.ValidateAudience

Added in version 6.11.0

Controls whether the token audience is validated.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEAUDIENCE
App config keyServiceControl.Audit/Authentication.ValidateAudience
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/Authentication.ValidateLifetime

Added in version 6.11.0

Controls whether the token expiration is validated.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATELIFETIME
App config keyServiceControl.Audit/Authentication.ValidateLifetime
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/Authentication.ValidateIssuerSigningKey

Added in version 6.11.0

Controls whether the token signing key is validated.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_VALIDATEISSUERSIGNINGKEY
App config keyServiceControl.Audit/Authentication.ValidateIssuerSigningKey
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/Authentication.RequireHttpsMetadata

Added in version 6.11.0

Controls whether HTTPS is required when retrieving metadata from the authority.

ContextName
Environment variableSERVICECONTROL_AUDIT_AUTHENTICATION_REQUIREHTTPSMETADATA
App config keyServiceControl.Audit/Authentication.RequireHttpsMetadata
SCMU fieldN/A
TypeDefault value
booltrue

TLS

These settings configure HTTPS. Refer to the hosting and security guide, or TLS configuration examples for additional information.

ServiceControl.Audit/Https.Enabled

Added in version 6.11.0

Enables Kestrel HTTPS with a certificate.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_ENABLED
App config keyServiceControl.Audit/Https.Enabled
SCMU fieldN/A
TypeDefault value
boolfalse

ServiceControl.Audit/Https.CertificatePath

Added in version 6.11.0

The path to the PFX or PEM certificate file.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPATH
App config keyServiceControl.Audit/Https.CertificatePath
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl.Audit/Https.CertificatePassword

Added in version 6.11.0

The password for the certificate file, if required.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_CERTIFICATEPASSWORD
App config keyServiceControl.Audit/Https.CertificatePassword
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl.Audit/Https.RedirectHttpToHttps

Added in version 6.11.0

Redirects HTTP requests to HTTPS. This is intended for use with a reverse proxy that handles both HTTP and HTTPS traffic.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_REDIRECTHTTPTOHTTPS
App config keyServiceControl.Audit/Https.RedirectHttpToHttps
SCMU fieldN/A
TypeDefault value
boolfalse

ServiceControl.Audit/Https.Port

Added in version 6.11.0

The HTTPS port to use in redirect URLs. Required when RedirectHttpToHttps is enabled in reverse proxy scenarios.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_PORT
App config keyServiceControl.Audit/Https.Port
SCMU fieldN/A
TypeDefault value
intNone

ServiceControl.Audit/Https.EnableHsts

Added in version 6.11.0

Enables HTTP Strict Transport Security (HSTS).

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_ENABLEHSTS
App config keyServiceControl.Audit/Https.EnableHsts
SCMU fieldN/A
TypeDefault value
boolfalse

ServiceControl.Audit/Https.HstsMaxAgeSeconds

Added in version 6.11.0

The max-age value in seconds for the HSTS header.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_HSTSMAXAGESECONDS
App config keyServiceControl.Audit/Https.HstsMaxAgeSeconds
SCMU fieldN/A
TypeDefault value
int31536000 (1 year)

ServiceControl.Audit/Https.HstsIncludeSubDomains

Added in version 6.11.0

Includes subdomains in the HSTS policy.

ContextName
Environment variableSERVICECONTROL_AUDIT_HTTPS_HSTSINCLUDESUBDOMAINS
App config keyServiceControl.Audit/Https.HstsIncludeSubDomains
SCMU fieldN/A
TypeDefault value
boolfalse

Forwarded headers

These settings configure forwarded headers for reverse proxy scenarios. Refer to the hosting and security guide, or forward headers configuration examples for additional information.

ServiceControl.Audit/ForwardedHeaders.Enabled

Added in version 6.11.0

Enables processing of forwarded headers (X-Forwarded-For, X-Forwarded-Proto, etc.).

ContextName
Environment variableSERVICECONTROL_AUDIT_FORWARDEDHEADERS_ENABLED
App config keyServiceControl.Audit/ForwardedHeaders.Enabled
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/ForwardedHeaders.TrustAllProxies

Added in version 6.11.0

Trusts forwarded headers from any source. Set to false when using KnownProxies or KnownNetworks.

ContextName
Environment variableSERVICECONTROL_AUDIT_FORWARDEDHEADERS_TRUSTALLPROXIES
App config keyServiceControl.Audit/ForwardedHeaders.TrustAllProxies
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/ForwardedHeaders.KnownProxies

Added in version 6.11.0

A comma-separated list of trusted proxy IP addresses e.g., 127.0.0.1

ContextName
Environment variableSERVICECONTROL_AUDIT_FORWARDEDHEADERS_KNOWNPROXIES
App config keyServiceControl.Audit/ForwardedHeaders.KnownProxies
SCMU fieldN/A
TypeDefault value
stringNone

ServiceControl.Audit/ForwardedHeaders.KnownNetworks

Added in version 6.11.0

A comma-separated list of trusted CIDR network ranges e.g., 10.0.0.0/8,172.16.0.0/12

ContextName
Environment variableSERVICECONTROL_AUDIT_FORWARDEDHEADERS_KNOWNNETWORKS
App config keyServiceControl.Audit/ForwardedHeaders.KnownNetworks
SCMU fieldN/A
TypeDefault value
stringNone

CORS

These settings configure Cross-Origin Resource Sharing (CORS). Refer to the hosting and security guide, or cors configuration examples for additional information.

ServiceControl.Audit/Cors.AllowAnyOrigin

Added in version 6.11.0

Allows requests from any origin.

ContextName
Environment variableSERVICECONTROL_AUDIT_CORS_ALLOWANYORIGIN
App config keyServiceControl.Audit/Cors.AllowAnyOrigin
SCMU fieldN/A
TypeDefault value
booltrue

ServiceControl.Audit/Cors.AllowedOrigins

Added in version 6.11.0

A comma-separated list of allowed origins e.g., https://servicepulse.example.com,https://admin.example.com

ContextName
Environment variableSERVICECONTROL_AUDIT_CORS_ALLOWEDORIGINS
App config keyServiceControl.Audit/Cors.AllowedOrigins
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
stringWarn

Valid settings are: Trace, Debug, Info, Warn, Error, Fatal, Off.

Raven/IndexStoragePath

The path for the indexes on disk.

ContextName
Environment variableRAVEN_INDEXSTORAGEPATH
App config keyRaven/IndexStoragePath
SCMU fieldN/A
TypeDefault value
string%SYSTEMDRIVE%\ProgramData\Particular\ServiceControl\<instance_name>\DB\indexes

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.Audit/IngestAuditMessages

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

ContextName
Environment variableSERVICECONTROL_AUDIT_INGESTAUDITMESSAGES
App config keyServiceControl.Audit/IngestAuditMessages
SCMU fieldN/A
TypeDefault value
booltrue

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

This controls the batch size used when deleting audit messages that have exceeded the audit retention period.

ContextName
Environment variableSERVICECONTROL_AUDIT_EXPIRATIONPROCESSBATCHSIZE
App config keyServiceControl.Audit/ExpirationProcessBatchSize
SCMU fieldN/A
TypeDefault value
int65512

The minimum allowed value for this setting is 10240; there is no hard-coded maximum as this is dependent on system performance.

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

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 primary instance queue name to use to send 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
stringParticular.ServiceControl

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

Raven/Esent/LogsPath

This setting is applicable only on instances that use the RavenDB 3.5 storage engine.

The path for the Esent logs on disk.

TypeDefault value
string%SYSTEMDRIVE%\ProgramData\Particular\ServiceControl\<instance_name>\DB\Logs