BizTalk Server 2013 R2: Instrumenting an orchestration with ETW

Article
1/17/2024

Introduction

The BizTalk CAT Instrumentation Framework provides a reusable framework intended to help BizTalk developers enrich their solutions with high-performance instrumentation based on the Event Tracing for Windows (ETW) infrastructure. As a developer you can instrument your BizTalk artefact, WCF/WF component, or custom component (.NET) for the purpose of logging, tracing or testing to observe behavior. ETW enables you to log kernel or application events to a log file. An application can be monitored in total, meaning that a BizTalk solution containing custom pipeline components, mappings, and an orchestration can be logged from end to end. This can also be done using log4net or System.Diagnostics namespace.

The framework was built as a result of research within Microsoft which found both log4net and System.Diagnostics did not deliver enough agility or acceptable performance. ETW infrastructure within the Microsoft OS provided a high-speed tracing facility and combined with a TracePovider in from the Microsoft.BizTalk.Diagnostics namespace in Microsoft.BizTalk.Tracing.dll are basically the main ingredients of the framework. The most important part within the framework is the ComponentTraceProvider class. This class is a wrapper around the TraceProvider providing various tracing methods for common logging requirements such as information, warning, and exceptions. In addition to these methods the team also enriched the framework with support for tracing method calls, measuring durations using high-resolution timers and ability to correlate events using Guid-based tokens.

Scenario

The BizTalk CAT Instrumentation Framework can be used to instrument the following BizTalk artifacts:

Custom Pipeline Components
BizTalk Mapping
Orchestrations
Business Rules
BAM Activity Tracking Components

The following scenario will demonstrate how to instrument an orchestration. In this article the Compensation sample from the SDK will be used. The sample is a part of sample to be found in the SDK folder of the BizTalk installation (i.e. <install directory>:\Program Files (x86)\Microsoft BizTalk Server 2013 R2\SDK). This sample will be
demonstrate how you can use the compensation shape in an orchestration. It will be combined with the ETW.

Prerequisites

To leverage ETW for BizTalk you will to download the BizTalk CAT Instrumentation Framework v1.4 and build it locally on your machine with Visual Studio 2013. You will need to open the solution with Visual Studio 2013 to migrate to newer version of the .NET framework. To build the project the following code in class IcomponentTraceProvider needs to be commented out:

void TraceInfo(Func<string> expensiveDataProvider);

Next to the Instrumentation Framework you can download the BizTalk CAT Instrumentation Framework Controller, which is an easy-to-use GUI for the BizTalk CAT Instrumentation Framework. This will let you start and stop a traces and adjust filter options. It can easily enable real-time tracing to the Microsoft SysInternals DebugView (or other debuggers), or to a log file or to do both at the same time.

Instrumenting an orchestration with the BizTalk CAT Instrumentation Framework

An orchestration can be instrumented using TraceManager.WorkflowComponent, which is designed for the purpose this BizTalk artefact. The TraceManager can be useful to test:

Tracing calls in the orchestration flow at start and end using TraceIn and TraceOut;
Measuring the duration of the above methods using TraceStartScope and TraceEndScope, which will be demonstrated in the orchestration
Tracing the internal state of the in this case custom archiving pipeline component, which could in turn assist with troubleshooting using TraceInfo;
Writing detailed information about a runtime exception using TraceError in case an error occurs in the flow.

http://i208.photobucket.com/albums/bb152/Steef-Jan/ETW/Orch%20ETW%201_zpscue7pgsl.png

Figure 1. Scenario using ETW with an orchestration.

The BizTalk CAT Instrumentation Framework in action

To capture and review the behavior of the orchestration a specific message will be offered to BizTalk to trigger the flow. Before the message is sent the BizTalk CAT Instrumentation Framework Controller will be launched. Selecting the Orchestration/Workflow component trace filter setting:

http://i208.photobucket.com/albums/bb152/Steef-Jan/ETW/Orch%20ETW%202_zpsm6vv9sxn.png

Picture 2. BizTalk CAT Instrumentation Controller.

DebugView will be launched. The message will be place in a folder. The debug trace will look like below in the DebugView:

http://i208.photobucket.com/albums/bb152/Steef-Jan/ETW/Orch%20ETW%203_zpsvnghtznn.png

Picture 3. DebugView capturing the traces.

When the text editor will be opened that the same trace information displayed in debugview can be found.

http://i208.photobucket.com/albums/bb152/Steef-Jan/ETW/Orch%20ETW%204_zpsyfsfsb2p.png

Picture 4. Captured trace information in text editor notepad++.

The calltoken is used in each TraceInfo statement, TraceStartScope and TraceEndScope to correlate the tracing statements.

Wrap up

This article demonstrated how to instrument an orchestration with the BizTalk CAT Instrumentation Framework that leverages Event Tracing for Windows (ETW), which is able to trace in a very performant way to a log file. ETW is suitable to be used with mappings, pipelines, custom code, BRE and BAM. Examples on how to instrument them is similar to a custom pipeline component. Various samples can be found online demonstrating that like the excellent blog post Best Practices for Instrumenting High Performance BizTalk Solutions written by the team that build the BizTalk CAT Instrumentation Framework. The BizTalk CAT Instrumentation Framework Controller can be seen as a add-on for the framework to stop/start traces and specify options for enabling debugview and a texteditor.

Share via