Starting, Stopping, and Formatting XMLTracer Output

  • [アーティクル]

One of the main design advantages of the XMLTracer pipeline component is its ability to be turned on and off independently of the pipelines into which it has been added. In other words, you can add one or more instances of the XMLTracer pipeline component to one or more pipelines, and then use a command line program to control whether those instances are active or not, and when active, the level of their activity. This can be useful when the issues you are investigating are transient or difficult to reproduce. After you are able to reproduce the issue, you can activate the XMLTracer pipeline component(s) that you have placed in your pipelines without disrupting the state of your application.

After you have captured the OrderForm data using the XMLTracer pipeline component, you must use another command line program to format the output of the XMLTracer pipeline component so that you can view and analyze it.

XMLTracer Support Files

The following files are installed into the folder %Commerce_Server_Root%\Support and are used in conjunction with the XMLTracer pipeline component:

  • Tracelog.exe. Use this command line program to start and stop the XMLTracer pipeline component(s) that you have placed into your pipeline(s). Tracelog.exe has a wide variety of command line options. Use the -? option to see a description of all of the options.

    The following example command shows how to start an XMLTracer trace log session, outputting to the log file c:\cstrace.etl with a flush timer of 5 seconds and buffer size of 512 kilobytes. It assumes that you have already changed directories to %COMMERCE_SERVER_ROOT%\Support".

    .\tracelog.exe -start cstrace -guid #B3357239-9CCE-4D9D-A4AC-79EFC917F6A4 -f c:\cstrace.etl -flags 4 -ft 5 -b 512

    The following example command shows how to stop the tracing session started with the previous command.

    .\tracelog.exe -stop cstrace

  • Tracefmt.exe. Use this command line program to format the output of the XMLTracer pipeline component so that you can view and analyze it. Tracefmt.exe has several command line options. Use the -? option to see a description of all of the options.

    Note

    It is not necessary to stop tracing before formatting the log file. However, there may be some trace data in memory that has not been flushed out to the disk file. Therefore, it is recommended that you stop tracing before formatting the log file.

    The following example command shows how to format the log file produced by the example commands provided for Tracelog.exe above.

    .\tracefmt.exe -f c:\cstrace.etl -tmf .\TraceFormat\XmlTracer.tmf

  • Traceprt.dll. This DLL is required by the Tracefmt.exe command line program. You should make sure that this DLL is in the same folder and the program Tracefmt.exe.

  • XmlTracer.tmf. This file is used by the Tracefmt.exe program to format the output of the XMLTracer pipeline component and may be specified as a command line parameter.

  • Cstraceguids.ctl. This file provides the GUIDs of the various entities within Commerce Server Core Systems that you can trace using the XMLTracer pipeline component. This file must be in the same folder from which you are running the command line programs Tracelog.exe and Tracefmt.exe.

  • Cstraceguids.ctl. This file provides the GUIDs for all of the components in Commerce Server Core Systems that support ETW tracing. Trace format files are provided only for the XmlTracer component logs and for the trace logs provided by managed code components that utilize the TraceEvent.dll assembly for outputting trace information. Trace output from other components may only be formatted by authorized Microsoft support professionals. The following components utilize TraceEvent.dll for tracing:

    • TransactionHelper

    • CommerceServer_Marketing

    • CommerceServer_Orders

    • CommerceServer_Staging

    • CommerceServer_Catalog

    You can selectively trace Commerce Server Core Systems components by editing the cstraceguids.ctl file. Comment out the GUIDs of trace providers that you do not want to trace by prefixing their GUIDs with the "#" character. The remaining trace providers, with GUIDs that have not been commented out, will output trace information into the log.

    To start a tracing session with multiple ETW providers, as specified in the cstraceguids.ctl file, use a command line similar to the following from the "%COMMERCE_SERVER_ROOT%\Support" directory:

    .\tracelog.exe -start cstrace -guid cstraceguids.ctl -f c:\cstrace.etl -flags 4 -ft 5 -b 512

    To stop tracing and format the trace log file, use the following commands:

    .\tracelog.exe -stop cstrace 
.\tracefmt.exe -f c:\cstrace.etl -tmf .\TraceFormat\XmlTracer.tmf -tmf .\TraceFormat\CSTraceEvents.tmf

Example Output

The XMLTracer pipeline component breaks large XML traces into chunks of memory to prevent overrunning the trace buffers and losing data. If XMLTracer_Comment is set, it precedes each chunk in the trace with a header containing the configured comment, as well as the date and time, and the chunk number.

The following code fragment is from an XMLTracer run. The fragment uses the "Debugging Comment" and the output is split into five XML chunks.

[0]011C.0F60::11/24/2003-18:21:18.859 [XMLTracer.cpp](Debugging Comment): XMLTrace of Order (chunk 1/5): <DICTIONARY xmlns:dt="uuid:304FB305-29A4-11d3-B0D4-00C04F8ED7A2" version="1.0">
<DICTITEM key="_Purchase_Errors"><VALUE dt:dt="object" dt:classid="classid:B7990D0E-45FD-11D0-8176-00A0C90A90C7">
<SIMPLELIST xmlns:dt="uuid:304FB305-29A4-11d3-B0D4-00C04F8ED7A2" version="1.0">
</SIMPLELIST>
</VALUE></DICTITEM>
<DICTITEM key="_Basket_Errors"><VALUE dt:dt="object" dt:classid="classid:B7990D0E-45FD-11D0-8176-00A0C90A90C7">
<SIMPLELIST xmlns:dt="uuid:304FB305-29A4-11d3-B0D4-00C04F8ED7A2" version="1.0">
</SIMPLELIST>
</VALUE></DICTITEM>

See Also

Other Resources

Logging, Tracing and Exception Management in Commerce Foundation

What Are the XMLTracer Trace Levels?

What Are the XMLTracer Configuration Options?

What Are the Limitations of the XMLTracer Component?

Using the XMLTracer Pipeline Component