Tracking Events in the Tracking Database
You can also capture XLANG events in the tracking database. This is particularly useful when you want to correlate actions performed by an instance of an XLANG schedule on specific message instances flowing in and out of BizTalk Messaging Services. The BizTalk Document Tracking Web application allows you to query the database for document flows between organizations or applications. The XLANG events captured in the database can be viewed in relationship with the message flows displayed by the document tracking Web application.
This functionality of capturing tracking events is not part of the base installation of BizTalk Server. You must deploy a sample application called WorkFlowAudit to use this feature. This sample comes in two parts: one is a dynamic link library (DLL) that does the work of posting events raised by the scheduler into the database, and the other is a small graphical user interface (GUI) to start and stop this capture. The samples, along with the source code, are located at (or a similar location, depending on your installation):
Program FilesMicrosoft BizTalk ServerSDKXLANG Samples... ...WorkFlowAuditinWorkFlowAudit.dll ...WorkFlowAuditClientWorkFlowAuditClient.exe
To use this sample, you must first register the WorkFlowAudit.dll. Next, run the WorkFlowAuditClient.exe client application. The client application allows you to specify the database connection information, although the defaults are based on the current configuration. Now, you can start and stop the event capture using buttons on the client GUI.
Note
Event capture stops if you close the WorkFlowAuditClient.exe application. You would normally expect such a mechanism to be implemented as a background system process; however, it is currently provided as an interactive application.
The event data is captured into the tracking database tables dta_wf_EventData and dta_wf_WorkFlowEvent.Table 11.9 shows the structure of these tables.
| Field | Description |
|---|---|
| nWorkflowEventId | Auto-incremented key field. Provides a link to the dta_wf_EventData rows. |
| nvcEventId | The event type. This is a GUID constant—an identity for the event. |
| nvcEventName | Event name. The event names that you will see are provided in Listing 11.3. All names begin with OnBTA. |
| nProcessId | The process ID of the group manager that hosted the schedule instance that generated the event. |
| nvcApplicationId | The GUID identity of the group manager (COM+ application). |
| nvcInstanceId | The GUID identity of the XLANG schedule instance. This is the identity visible in the XLANG Event Monitor. |
| nEventTime | UTC (Universal Coordinated Time) time of this event, as seconds elapsed since midnight, January 1, 1970. |
| nEventSubTime | Time offset in microseconds. |
| nEventTick | Value of the high-resolution performance counter at the time of the event. |
| nvcServerName | Server on which the event was detected. |
| dtDateEntered | Date and time of the event. |
A row in dta_wf_WorkFlowEvent table denotes a single event. The detailed attributes of each such event are captured in dt_wf_EventData. This table contains multiple rows corresponding to an event, each row with a specific attribute of the event. Table 11.10 shows the dt_wf_EventData table.
| Field | Description |
|---|---|
| nEventDataId | Auto-incremented key field. |
| nWorkFlowEventId | Foreign key to the parent event record in dt_wf_WorkFlowEvent table. |
| nvcName | Name of the event attribute. |
| One particular attribute of interest is the CorrelationID attribute. Messaging events have such an attribute. The value of this attribute is a GUID, which is used to correlate with messages flowing through BizTalk Messaging Services. | |
| nvcValue | The value of the attribute named in nvcName. This can be anything; however, for CorrelationID, it is a GUID. |
The tables of the tracking database are documented as part of the BizTalk product documentation. You could, if you feel up to it, write SQL queries to mine specific data from the tracking database, for problem isolation, for example. The event names that you are likely to find are provided in Listing 11.3. You can see these event names in the XLANG Event Monitor.
Listing 11.3. Event Names in Tracking Database
OnBTAAppError OnBTACallEnter OnBTACallLeave OnBTACaseExecute OnBTAComSinkCall OnBTAComSinkReturn OnBTAComSourceCall OnBTAComSourceReturn OnBTAConnectEnter OnBTAConnectLeave OnBTAContextAbort OnBTAContextCompensate OnBTAContextEnter OnBTAContextLeave OnBTADehydrated OnBTAError OnBTAMSMQDeliver OnBTAMSMQReceive OnBTAPartitionEnter OnBTAPartitionLeave OnBTAProxyEnter OnBTAProxyLeave OnBTARehydrated OnBTAReturnEnter OnBTAReturnLeave OnBTAScheduleDone OnBTAScheduleFailFast OnBTASchedulePersist OnBTAScheduleResume OnBTAScheduleStart OnBTAScheduleStop OnBTAScheduleSuspend OnBTAShutdown OnBTASinkEnter OnBTASinkLeave OnBTASourceEnter OnBTASourceLeave OnBTAStartup OnBTASwitchEnter OnBTASwitchLeave OnBTATaskEnter OnBTATaskLeave OnBTATransactionBegin OnBTATransactionEnd |
Although a deeper understanding of the tracking database is useful for design and troubleshooting, schedule development can be done using the XLANG Event Monitor and the document tracking Web application.
The BizTalk Document Tracking application is used to locate and view document interchange information recorded in the tracking database. The tracking application is described in Chapter 8, “Document Tracking.” With the WorkFlowAudit sample described earlier, you can also add tracking information for document interchanges that flow between BizTalk Messaging and Orchestration Services. In the tracking application, you select the source, destination, and documents that you want to view tracking data for. You can also narrow your search to a specified time period.
After making your selections, you query the tracking database. The results of the query show the tracking information for document interchanges that occurred. You can look at the document or interchange actually handled in both the native and XML format. Along with this information, you can also view the events logged by the running XLANG schedule, the same information you saw in the XLANG Event Monitor but shown in relation to the document interchange. The events are shown in the tracking application with their name, attribute, and value. The events are shown in Listing 11.3.