Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion servicecontrol/audit-instances/deployment/powershell.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ include: powershell-new-configuration
> [!NOTE]
> The address of a ServiceControl Error instance must be provided to send notifications to.

Once a ServiceControl Audit instance is created, it must be added to the ServiceControl Error instance as a [remote](/servicecontrol/servicecontrol-instances/remotes.md) to be included in results returned to [ServiceInsight](/serviceinsight/) or [ServicePulse](/servicepulse/). Use the `Add-ServiceControlRemote` cmdlet to add a remote to the Error instance:
Once a ServiceControl Audit instance is created, it must be added to the ServiceControl Error instance as a [remote](/servicecontrol/servicecontrol-instances/remotes.md) to be included in results returned to [ServicePulse](/servicepulse/). Use the `Add-ServiceControlRemote` cmdlet to add a remote to the Error instance:

snippet: ps-add-audit-remote

Expand Down
7 changes: 3 additions & 4 deletions servicecontrol/audit-instances/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ redirects:
- servicecontrol/audit-instances/persistence
---

Each endpoint in the system can be [configured to send audit copies of every message that is processed into a central audit queue](/nservicebus/operations/auditing.md). ServiceControl Audit instances consume and store the messages sent to the audit queue and make them available for visualizing message flows in [ServiceInsight](/serviceinsight/) or [ServicePulse](/servicepulse/).
Each endpoint in the system can be [configured to send audit copies of every message that is processed into a central audit queue](/nservicebus/operations/auditing.md). ServiceControl Audit instances consume and store the messages sent to the audit queue and make them available for visualizing message flows in [ServicePulse](/servicepulse/).

ServiceControl Audit can optionally forward these messages into an [audit log queue](configuration.md#transport-servicecontrol-auditforwardauditmessages) for further processing if required.

Expand All @@ -19,7 +19,6 @@ graph LR
SC[ServiceControl<br>Instance]
AuditQ --> SCA

ServiceInsight -.-> SC
ServicePulse -.-> SC
SCA --> AuditLog[Audit.Log<br>Queue]

Expand All @@ -30,10 +29,10 @@ graph LR
Data about audit messages is exposed via an HTTP API from a ServiceControl Error instance, which aggregates the data stored in [all connected ServiceControl Audit instances](/servicecontrol/servicecontrol-instances/remotes.md#overview-sharding-audit-messages-with-competing-consumers).

> [!IMPORTANT]
> Connecting ServiceInsight or ServicePulse directly to a ServiceControl Audit instance is not supported.
> Connecting ServicePulse directly to a ServiceControl Audit instance is not supported.

> [!NOTE]
> The ServiceControl HTTP API is designed for use by ServiceInsight or ServicePulse only and may change at any time. Use of this HTTP API for other purposes is discouraged.
> The ServiceControl HTTP API is designed for use by ServicePulse only and may change at any time. Use of this HTTP API for other purposes is discouraged.

## Persistence

Expand Down
2 changes: 1 addition & 1 deletion servicecontrol/capacity-and-planning.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ The location of the database has a significant impact on overall system performa

The storage size that ServiceControl requires depends on the production load and is directly related to the quantity and size of messages that flow into the system.

ServiceControl provides "recent-history" storage to support ServicePulse and ServiceInsight monitoring and debugging. This is different to a data archiving system that is intended to provide long-term archiving and storage (measured in years, subject to various business or regulatory requirements).
ServiceControl provides "recent-history" storage to support ServicePulse monitoring and debugging. This is different to a data archiving system that is intended to provide long-term archiving and storage (measured in years, subject to various business or regulatory requirements).

ServiceControl is configured with default expiration policies that delete old messages after predefined time periods. The expiration policies may be customized to decrease or increase the amount of time that data is retained, which impacts the storage requirements of ServiceControl.

Expand Down
2 changes: 1 addition & 1 deletion servicecontrol/contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ snippet: ServiceControlEventsConfig
snippet: MessageFailedHandler

> [!WARNING]
> Endpoints that subscribe to ServiceControl events should _not_ use the same `error` and `audit` queues as other endpoints. Using the same `error` queue could cause an infinite feedback loop if processing a `MessageFailed` message failed. Using the same `audit` queue will cause the processing of the `MessageFailed` messages to be included in the ServiceInsight and ServicePulse messages search results. This could confuse users searching for a given failure since both the failure and the failure notification will be shown. See also: [Recoverability](/nservicebus/recoverability/) and [Audit Queue Settings](/nservicebus/operations/auditing.md).
> Endpoints that subscribe to ServiceControl events should _not_ use the same `error` and `audit` queues as other endpoints. Using the same `error` queue could cause an infinite feedback loop if processing a `MessageFailed` message failed. Using the same `audit` queue will cause the processing of the `MessageFailed` messages to be included in the ServicePulse messages search results. This could confuse users searching for a given failure since both the failure and the failure notification will be shown. See also: [Recoverability](/nservicebus/recoverability/) and [Audit Queue Settings](/nservicebus/operations/auditing.md).


#### Registering the publisher for message-driven publish/subscribe
Expand Down
10 changes: 5 additions & 5 deletions servicecontrol/how.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,10 @@ summary: An overview of how ServiceControl collects and processes messages and d
reviewed: 2025-07-06
---

ServiceControl is a background process that will collect and store data and make it available via an HTTP API to ServicePulse and ServiceInsight.
ServiceControl is a background process that will collect and store data and make it available via an HTTP API to ServicePulse.

> [!NOTE]
> The ServiceControl HTTP API may change at any time. It is designed for use by ServicePulse and ServiceInsight only. The use of this HTTP API for other purposes is not supported.
> The ServiceControl HTTP API may change at any time. It is designed for use by ServicePulse only. The use of this HTTP API for other purposes is not supported.

## How ServiceControl receives data

Expand Down Expand Up @@ -57,7 +57,7 @@ graph LR

[Recoverability](/nservicebus/recoverability/) is an important feature in NServiceBus. It enables automatic retries and continuity within a system, as failed messages will be moved aside to allow other messages to be processed while the errors are investigated. Those error messages contain business data that must eventually be processed.

NServiceBus will move messages it cannot process to an [error queue](/nservicebus/recoverability/#fault-handling). This is where ServiceControl comes into play to consume these messages. ServiceControl will pick up the message from the queue and store it in its RavenDb database. After it is stored in the database, the message is made available to ServicePulse and ServiceInsight for visualization, retries, and other operations.
NServiceBus will move messages it cannot process to an [error queue](/nservicebus/recoverability/#fault-handling). This is where ServiceControl comes into play to consume these messages. ServiceControl will pick up the message from the queue and store it in its RavenDb database. After it is stored in the database, the message is made available to ServicePulse for visualization, retries, and other operations.

> [!NOTE]
> It is recommended not to provide end-users with the ability to retry messages. The message could fail again and end up in ServiceControl once again. It could be even more problematic when many messages are retried during a peak in message processing. This will result in even more messages being processed by an endpoint, causing valid messages to be delayed even longer. Potentially even more messages can fail due to locking in your saga persistence.
Expand All @@ -66,9 +66,9 @@ Find out more about [failed messages](/servicepulse/intro-failed-messages.md) in

### Audit instances

To enable ServiceInsight and ServicePulse to visualize the message flow through the system, ServiceControl must have access to every message that has been successfully processed by the system. This requires endpoints to [enable auditing](/nservicebus/operations/auditing.md). ServiceControl consumes these messages and stores them in its database.
To allow ServicePulse to visualize the message flow through the system, ServiceControl must have access to every message that has been successfully processed by the system. This requires endpoints to [enable auditing](/nservicebus/operations/auditing.md). ServiceControl consumes these messages and stores them in its database.

ServiceInsight or ServicePulse will retrieve the data from ServiceControl via the HTTP API and use header information (added by NServiceBus during message processing) to figure out which message caused other messages to be sent, including which sagas were accessed when the [SagaAudit plugin](/nservicebus/sagas/saga-audit.md) is configured in an endpoint.
ServicePulse will retrieve the data from ServiceControl via the HTTP API and use header information (added by NServiceBus during message processing) to figure out which message caused other messages to be sent, including which sagas were accessed when the [SagaAudit plugin](/nservicebus/sagas/saga-audit.md) is configured in an endpoint.

### Monitoring instances

Expand Down
4 changes: 2 additions & 2 deletions servicecontrol/import-failed-messages.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Messages can fail to be imported into the ServiceControl database for the follow

Messages that fail to be imported are stored in the ServiceControl database in the `FailedAuditImports` and `FailedErrorImports` collections.

In addition, a log with the failure reason is written for the message in the `%ServiceControl/LogPath%` ([error instances](/servicecontrol/servicecontrol-instances/configuration.md#logging-servicecontrollogpath)/[audit instances](/servicecontrol/audit-instances/configuration.md#logging-servicecontrol-auditlogpath)) `\FailedImports\{Audit|Error}\%failureid%.txt`. These messages will not be visible in ServiceInsight or ServicePulse.
In addition, a log with the failure reason is written for the message in the `%ServiceControl/LogPath%` ([error instances](/servicecontrol/servicecontrol-instances/configuration.md#logging-servicecontrollogpath)/[audit instances](/servicecontrol/audit-instances/configuration.md#logging-servicecontrol-auditlogpath)) `\FailedImports\{Audit|Error}\%failureid%.txt`. These messages will not be visible in ServicePulse.

## Failed message custom check

Expand All @@ -29,7 +29,7 @@ When a failed import is detected in the ServiceControl database, the [**Message

To reimport the failed messages, the instance must be shut down and started from a command line using one of the following commands:

While in import mode, ServiceControl or ServiceControl Audit will not process its input queues. Once the message is re-processed successfully, it is available in ServicePulse and ServiceInsight.
While in import mode, ServiceControl or ServiceControl Audit will not process its input queues. Once the message is re-processed successfully, it is available in ServicePulse.

The custom check will no longer be displayed if all failed imports have been successfully reimported.

Expand Down
4 changes: 2 additions & 2 deletions servicecontrol/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ isLearningPath: true

include: servicecontrol

For more information on how ServiceControl, ServicePulse, and ServiceInsight work together, refer to [the Particular Service Platform](/platform/) article. For a quick overview of the different instances, what they do and how to configure endpoints, refer to the [how does ServiceControl work](/servicecontrol/how.md) article.
For more information on how ServiceControl and ServicePulse work together, refer to [the Particular Service Platform](/platform/) article. For a quick overview of the different instances, what they do and how to configure endpoints, refer to the [how does ServiceControl work](/servicecontrol/how.md) article.

### ServiceControl instance types

Expand All @@ -17,7 +17,7 @@ There are three types of instances that can be created:
- [Error instances](/servicecontrol/servicecontrol-instances/)
This is the most commonly used ServiceControl instance and indispensable to ensure the smooth operation of an NServiceBus system. Together with ServicePulse, it provides the ability to visualize and retry failed messages.
- [Audit instances](/servicecontrol/audit-instances/)
Audit instances provide valuable information about the message flow through a system. Among other things, this is used by ServiceInsight and ServicePulse to help visualize a distributed system.
Audit instances provide valuable information about the message flow through a system. Among other things, this is used by ServicePulse to help visualize a distributed system.
- [Monitoring instances](/servicecontrol/monitoring-instances/)
Monitoring instances performance monitoring and analyzing additional metrics and are useful for keeping track of the health of a distributed system.

Expand Down
4 changes: 0 additions & 4 deletions servicecontrol/license.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,10 +49,6 @@ snippet: config-licensepath
> [!NOTE]
> This is the same setting to configure a license path for an NServiceBus 7 or lower endpoint. This license configuration option is [no longer supported in NServiceBus 8](/nservicebus/upgrades/7to8/#change-to-license-file-locations) or later endpoints.

## Using ServiceInsight

A machine-wide license file can be installed using [ServiceInsight](/serviceinsight/license.md) which can then be used by ServiceControl.

## Troubleshooting

### ServiceControl license was updated, but ServicePulse reports the license has expired
Expand Down
12 changes: 0 additions & 12 deletions servicecontrol/migrations/replacing-audit-instances/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,16 +40,13 @@ errorQ -- ingested by --> sc[ServiceControl<br/>Error]
auditQ -- ingested by --> sca[Original<br/>ServiceControl<br/>audit]
sc -. connected to .-> sca
sp[ServicePulse] -. connected to .-> sc
si[ServiceInsight] -. connected to .-> sc

classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF
classDef ServiceInsight fill:#878CAA,stroke:#585D80,color:#FFFFFF
classDef ServicePulse fill:#409393,stroke:#205B5D,color:#FFFFFF
classDef ServiceControlError fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px
classDef ServiceControlRemote fill:#A84198,stroke:#92117E,color:#FFFFFF

class endpoints Endpoints
class si ServiceInsight
class sp ServicePulse
class sc ServiceControlError
class sca ServiceControlRemote
Expand Down Expand Up @@ -81,16 +78,13 @@ auditQ -- ingested by --> sca2[New<br/>ServiceControl<br/>audit]
sc -. connected to .-> sca
sc -. connected to .-> sca2
sp[ServicePulse] -. connected to .-> sc
si[ServiceInsight] -. connected to .-> sc

classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF
classDef ServiceInsight fill:#878CAA,stroke:#585D80,color:#FFFFFF
classDef ServicePulse fill:#409393,stroke:#205B5D,color:#FFFFFF
classDef ServiceControlError fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px
classDef ServiceControlRemote fill:#A84198,stroke:#92117E,color:#FFFFFF

class endpoints Endpoints
class si ServiceInsight
class sp ServicePulse
class sc ServiceControlError
class sca,sca2 ServiceControlRemote
Expand All @@ -117,16 +111,13 @@ auditQ -- ingested by --> sca2[New<br/>ServiceControl<br/>audit]
sc -. connected to .-> sca[Original<br/>ServiceControl<br/>audit]
sc -. connected to .-> sca2
sp[ServicePulse] -. connected to .-> sc
si[ServiceInsight] -. connected to .-> sc

classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF
classDef ServiceInsight fill:#878CAA,stroke:#585D80,color:#FFFFFF
classDef ServicePulse fill:#409393,stroke:#205B5D,color:#FFFFFF
classDef ServiceControlError fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px
classDef ServiceControlRemote fill:#A84198,stroke:#92117E,color:#FFFFFF

class endpoints Endpoints
class si ServiceInsight
class sp ServicePulse
class sc ServiceControlError
class sca,sca2 ServiceControlRemote
Expand Down Expand Up @@ -159,16 +150,13 @@ errorQ -- ingested by --> sc[ServiceControl<br/>error]
auditQ -- ingested by --> sca2[New<br/>ServiceControl<br/>audit]
sc -. connected to .-> sca2
sp[ServicePulse] -. connected to .-> sc
si[ServiceInsight] -. connected to .-> sc

classDef Endpoints fill:#00A3C4,stroke:#00729C,color:#FFFFFF
classDef ServiceInsight fill:#878CAA,stroke:#585D80,color:#FFFFFF
classDef ServicePulse fill:#409393,stroke:#205B5D,color:#FFFFFF
classDef ServiceControlError fill:#A84198,stroke:#92117E,color:#FFFFFF,stroke-width:4px
classDef ServiceControlRemote fill:#A84198,stroke:#92117E,color:#FFFFFF

class endpoints Endpoints
class si ServiceInsight
class sp ServicePulse
class sc ServiceControlError
class sca2 ServiceControlRemote
Expand Down
4 changes: 2 additions & 2 deletions servicecontrol/migrations/replacing-error-instances/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ See [Replacing an Audit Instance](../replacing-audit-instances/) for similar gui

## Overview

ServiceControl Error instances serve as the central access point for both Error and Audit data. When ServicePulse or ServiceInsight requests data from the API, those requests are either answered by the Error instance directly or passed through to one or more Audit instances in a scatter/gather pattern. So it is possible to create a new Error instance configured to communicate with the same Audit instance(s) and begin using the new Error instance to consume messages from the error queue. The critical aspect is to protect any active error messages during the transition that might still contain any valuable business data.
ServiceControl Error instances serve as the central access point for both Error and Audit data. When ServicePulse requests data from the API, those requests are either answered by the Error instance directly or passed through to one or more Audit instances in a scatter/gather pattern. So it is possible to create a new Error instance configured to communicate with the same Audit instance(s) and begin using the new Error instance to consume messages from the error queue. The critical aspect is to protect any active error messages during the transition that might still contain any valuable business data.

Keeping this in mind, an Error instance that can't be upgraded can be replaced without downtime. The process follows these steps:

Expand Down Expand Up @@ -63,4 +63,4 @@ Now that the only valuable error messages are held in the error queue, the Error

Once complete, the old Error instance has been successfully replaced with a new one.

If the procedure involved creating a new instance, rather than a forced upgrade, it will be necessary to adjust the connection information for ServicePulse and ServiceInsight to connect to the new Error instance's URL.
If the procedure involved creating a new instance, rather than a forced upgrade, it will be necessary to adjust the connection information for ServicePulse to connect to the new Error instance's URL.
2 changes: 1 addition & 1 deletion servicecontrol/migrations/windows-to-containers.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ When the objective is to migrate from Windows hosting to container-based hosting

## Migrating Audit instances

Migration of an Audit instance is only necessary if audit message data must be preserved. Audit data is regularly deleted after it reaches the end of its retention period, so when considering a migration, it's necessary to consider whether the value of the audit data, as used by ServiceInsight and ServicePulse, is worth the added complexity of the migration procedure.
Migration of an Audit instance is only necessary if audit message data must be preserved. Audit data is regularly deleted after it reaches the end of its retention period, so when considering a migration, it's necessary to consider whether the value of the audit data, as used by ServicePulse, is worth the added complexity of the migration procedure.

See the article [Replacing an Audit instance](/servicecontrol/migrations/replacing-audit-instances/) for migration instructions. The procedure includes creating a new audit instance in parallel with the old one, and disabling audit ingestion on the old instance. In this way, audit data is served from both instances until all the audit data in the Audit instance reaches its retention period and is deleted, after which the old audit instance can be removed.

Expand Down
Loading