When an NServiceBus endpoint fails to process a message, it performs a set of configurable attempts to recover from this message failure. These attempts are referred to as "immediate retries" and "delayed retries" and in many cases allow the endpoint to overcome intermittent communication failures. See recoverability for more details.
If the automatic retry attempts also fail, the endpoint forwards the failed message to the central error queue defined for all endpoints in the system. See Auditing with NServiceBus for more details.
ServicePulse (via ServiceControl) monitors the central error queue and displays the current status and details of failed messages as an indicator in the ServicePulse dashboard.
In addition, ServicePulse also provides a Failed Messages page to assist in examining failed messages and taking certain actions on them.
Both the "Failed Messages" indicator in the Dashboard and the "Failed Messages" link in the navigation bar link to the Failed Messages screen. This page is split into various tabs.
The first tab in the Failed Messages page shows error groups. A group is a set of failed messages grouped according to criteria like, for example, the same exception type.
This tab shows two lists, described below.
This list is collapsed by default and shows information about the last 10 completed group retry requests.
A completed retry request represents a completed operation where messages from a given group were sent to the corresponding queue for processing. This means those messages may not actually have been processed yet. Learn more about retrying failed messages.
This list shows all groups of currently failed messages.
The display of failed message groups can be changed via the "Group by" drop down menu, according to the following classifications types:
- Exception Type and Stack Trace - groups messages both by exception type and stack trace. It is the default way of categorizing failed messages.
- Message Type - groups messages by message type.
The following actions can be performed on a failed message group:
- View messages - Shows all individual messages contained in the group.
- Request retry - Sends all failed messages to the corresponding queue to attempt processing again. When a failed group retry request is initiated, ServicePulse will present the progress of the operation.
- Archive group - Archives all messages contained in the group. Learn more about archiving messages.
Individual messages views allow for accessing in-depth details about a given failed message, or retrying individual messages.
Individual failed messages can viewed using one of the following two ways:
- Inside a failed message groups - in the "Failed Messages Group" tab, click the "View messages" link from a failed message group entry
- All messages without any grouping - in the "All messages" tab
Both of these individual message list views allow for taking actions on an individual message, on custom message selections or on all messages contained in the view.
The following actions can be taken on each individual message:
- Message Details: For a given failed message, displays the message type, exception description, endpoint name and location, and failure timestamp.
- StackTrace: Displays the full .NET exception stacktrace.
- Headers: Displays a complete set of message headers.
- Body: Displays the serialized message body.
- Copy Message Id: Copies the failed message unique ID to the clipboard.
- Open in ServiceInsight: Launches ServiceInsight, focusing on the failed message for in-depth analysis of the failure causes. This only works if ServiceInsight is installed on the local machine.
Failed messages that cannot be processed successfully (or should not be retried due to various application-specific reasons) can be archived.
Learn more about archiving messages in ServicePulse.