1. Problem
Your integration solution has encountered an error, and you must determine what caused the fault.
2. Solution
A variety of tools can be
used for troubleshooting suspended instances. The BizTalk Administrator
Console is the first place to look in helping to identify why errors
occur in an integration solution and to determine the best way to fix
them. Other tools include the Windows event log, SQL Server, and other
external applications.
Often, the event log gives
the first indication an error has occurred in BizTalk, especially during
the development stages of an integration project. BizTalk Server writes
errors to the application event log each time it suspends a service
instance. The error event contains helpful information on when, why, and
where the fault happened. You can view errors posted to the event log
by BizTalk Server through the BizTalk Administrator Console, which
includes the Event Viewer MMC snap-in.
Frequently, the event log
will have enough information to determine what action needs to be taken
to fix the error (server name not specified on the SMTP adapter, for
example), but often, further troubleshooting is necessary. To obtain
more detailed information about the fault, you can use the BizTalk
Administrator Console's Group Hub page, which provides a number of ways
to search for suspended service instances.
The following steps outline a procedure for troubleshooting a suspended service.
Open the BizTalk Administration Console.
Expand the Event Viewer
folder in the left pane, click Windows Logs, and select Application.
You should see an error event relating to the service instance that was
suspended. This event is flagged with a BizTalk related source, such as
BizTalk Server or XLANG/s. See Figure 1.
To obtain more detailed information about the event, expand the BizTalk Server Administration folder in the left pane, and select your BizTalk group. This opens the Group Hub page.
Click
the Suspended service instances link in the Suspended Items section.
Clicking this link launches a query window, as shown in Figure 2.
NOTE
The Group Hub page also
provides filtered views of suspended service instances, including
resumable service instances; nonresumable service instances; suspended
MSMQT messages; and suspended service instances grouped by application,
error code, service name, and URI. All queries are customizable.
Order
the query results on the Creation Time column by clicking the column
header. You can compare the creation date with the timestamp of the
error event log entry to determine if they relate to one another.
Once
you have found the appropriate suspended service instance in the query
results list, double-click the row to launch the Service Details dialog
box, as shown in Figure 3.
The General tab of this dialog box includes high-level information
regarding the suspended instance, including the BizTalk component that
encountered the error, the service's status, and the instance ID.
Knowing the particular component that encountered the error is a
valuable and significant piece to the troubleshooting puzzle, as it
assists in narrowing down where the fault occurred.
Click the Error Information tab. As shown in Figure 4,
this tab displays the text of the exception that the suspended service
instance encountered, which is the same as what is written to the
application event log. The error text usually includes key stack
information, indicating at what level the fault occurred and how it was
bubbled up through BizTalk. In our example, the instance was suspended
because the send port was stopped.
Click the Messages tab. As shown in Figure 5,
the Messages tab displays a list of all messages related to the
suspended service instance. From this tab, you can save the suspended
message to a file for further inspection, turn on tracking for the
message, or view additional details of the message (right-click the
message for these capabilities).
Double-click one of the messages, and select the Context section, as shown in Figure 6.
This view displays the context of the suspended message, which can be
especially helpful when troubleshooting. Particularly, it alerts you to
what properties the message had when it was suspended and which were
promoted.
3. How It Works
When errors occur in your integration solutions, BizTalk typically suspends the service instance encountering the error. Service is a generic term used to describe an area of BizTalk processing, such as orchestration, messaging, or adapter. Service instance
refers to a specific instance of the orchestration, messaging, or
adapter component. The troubleshooting tools of BizTalk are primarily
used by system/solution administrators and are not typically used (in a
production environment) by developers or testers.
Finding the particular
suspended service instance you are troubleshooting is the first step in
solving the issue. In this recipe's solution, we compared the timing of
event log errors and suspended services to find a specific instance.
This technique of timestamp comparison would not work well if you were
troubleshooting a long-running service instance (in which case, the
creation time of the instance and the time of the error may be
significantly different). While our solution used a simple way of
locating the suspended instance, more-advanced methods can be useful,
especially in production, heavy-load, or long-running environments.
You can search for
instances based on all sorts of information. To add additional filter
criteria to the report, in the BizTalk Administration Console, take the
following steps:
Click a new row in the Query Expression pane, under the Field Name column.
Add the desired column, as shown in Figure 7.
The BizTalk Administration
Console also allows you to create your own queries to find suspended
service instances. Click the New Query tab (shown in Figure 8)
available in the BizTalk Group Hub Overview area. You can save and
retrieve custom queries for future troubleshooting needs (a query can be
saved by using the Save As button and storing the file for later
retrieval).
Once you have found your
suspended service instance, the details that BizTalk Server tracks
against the suspended instance provide a solid starting point for
determining the best way to fix the issue. In general, you should use
generic problem-solving skills when troubleshooting BizTalk errors:
break down the problem into its component parts, and use the tools at
your disposal to evaluate the fault using a bottom-up approach. Using
the BizTalk Administrative Console allows you to break down complex
solutions into manageable parts and troubleshoot the specific component
encountering the error.
