SagaAudit Plugin

Target Version: NServiceBus 6.x
Standard support for version 6.x of NServiceBus has expired. For more information see our Support Policy.
The following documentation describes deprecated packages ServiceControl.Plugin.Nsb5.SagaAudit and ServiceControl.Plugin.Nsb6.SagaAudit. To learn about the replacement package see NServiceBus.SagaAudit. To learn how to upgrade consult the upgrade guide.
For Development only. This plugin will result in a significant increase in the load placed on ServiceControl. As such it should not be used in production.

The SagaAudit plugin enables the Saga View feature in ServiceInsight. It is built specifically to help developers verify Saga logic during development. It does this by capturing Saga message behavior and changes in Saga data/state as the Saga is being processed. It then sends this information to a ServiceControl endpoint setup in the development environment.

Saga audit messages will not be sent to ServiceControl if an Exception is thrown during Saga processing.


The SagaAudit plugin captures the following information:

  • The incoming messages (including timeouts) that initiate change in the saga.
  • The outgoing messages that the saga sends.
  • A snapshot of the current saga data.
  • The saga state

All this information is sent to and stored in ServiceControl. Note that the saga audit data is transmitted to ServiceControl via a message and is serialized using the built in JSON Serializer of NServiceBus.

Impact on ServiceControl performance

This plugin results in an increase in load in several areas

  1. Endpoint load in order to capture the required information
  2. Network load due to the extra information sent to ServiceControl
  3. ServiceControl load in the areas of ingestion, correlation and data cleanup.

The increase in load is proportional to size of the saga data multiplied by the number of messages the the saga receives. Since both these variables are dependent on the specific saga implementation it is not possible to give accurate predictions on the impact of this load in a production system.

Deprecated NuGet Packages

The following SagaAudit plugin packages have been deprecated and unlisted. If using one of these versions replace package references to use NServiceBus.SagaAudit.

  • ServiceControl.Plugin.SagaAudit
  • ServiceControl.Plugin.Nsb5.SagaAudit
  • ServiceControl.Plugin.Nsb6.SagaAudit


ServiceControl Queue

Plugins send messages using the defined endpoint transport to ServiceControl. The plugin must be configured with the location of the ServiceControl input queue. This queue is created during the installation of ServiceControl. The queue name is based on the ServiceControl instance name which is visible in the ServiceControl Management utility.

Service Control Instance Name

Configure the ServiceControl queue via config:

  <add key="ServiceControl/Queue"
       value="particular.servicecontrol@machine" />

Configure the ServiceControl queue via code:

var endpointConfiguration = new EndpointConfiguration("myendpoint");
    serviceControlQueue: "particular.servicecontrol@machine");

Disabling plugin

var endpointConfiguration = new EndpointConfiguration("myendpoint");

Removing the plugin from Production

Removing the plugin before deployment to production depends on how the plugin is configured.

Disable plugin in production via config:

  1. Stop the endpoint.
  2. Delete the SagaAudit plugin dll from the endpoint's bin directory.
  3. If there is an automated deployment processes in place, ensure that this dll is no longer included.
  4. Restart the endpoint.

When the plugin is configured via code the endpoint has a direct reference to it. Removing the dll from the bin directory will prevent the endpoint from starting unless the configuration code is also removed. Rather create a configurable option in the config with which the plugin can be enabled or disabled. Configure this option during deployment to disable it in production.

var endpointConfiguration = new EndpointConfiguration("myendpoint");
if (isSagaPluginEnabled)
    serviceControlQueue: "particular.servicecontrol@machine");

Disabling the SagaAudit plugin will stop sending the saga state change messages to ServiceControl reducing message load to ServiceControl. Turn it back on if or when needed.

Temporarily debugging sagas in Production

To temporarily start visualizing a saga in production, the Saga Audit plugin can be deployed with the endpoint hosting the saga. Deploy the assembly at the same location as the endpoint is running, configure it and restart the endpoint. Use ServiceInsight to view the visualization and when done, follow the steps above to remove the plugin and restart the service.

Related Articles

Last modified