XMLTracer
The XMLTracer pipeline component is a troubleshooting and debugging tool that outputs the contents of the OrderForm object to a log file during any stage of pipeline execution.
Intended use: Troubleshooting pipeline-related issues that may occur in a production deployment. You can add the XMLTracer pipeline component to any stage of any pipeline.
For more information about how to use XMLTracer, see Using the XMLTracer Pipeline Component.
Configuration Values
By default, XMLTracer dumps the top-level Order dictionary). By setting special key values in the Order dictionary, you can tell it to dump only a specific subdictionary of the Order dictionary. You typically insert a Scriptor component into the pipeline before the XMLTracer component to set these values. However, you do not have to insert them; it is entirely optional.
Key |
Description |
|---|---|
XMLTracer_DictionaryToDump |
Specifies either a subdictionary of the OrderForm, or the special value Context. For example, use FilterRequire to dump the Content Selection Framework (CSF) filters in a Content Selection pipeline. Using Context causes the Context dictionary to be dumped. .gif "Note") Note:
Using Context might not work because the Context dictionary typically contains objects that cannot be serialized to XML.
|
XMLTracer_Comment |
Specifies a comment to insert into the log file. This is useful for distinguishing multiple traces in the same or different pipelines, making it easy to search the log file. |
For more information, see What Are the XMLTracer Configuration Options?
Values Read
The XMLTracer pipeline component is inactive until tracing is enabled. You use the flags parameter of tracelog.exe to specify trace levels as a bitwise OR value or as specified bit values. Tracelog.exe is a command-line tool used to enable and disable tracing.
XMLTracer responds to the following levels of debug tracing.
Flag value |
Description |
|---|---|
0x4 |
Enable XMLTracer. If this bit is not set, XMLTracer immediately returns without taking any action. If this is the only bit set, then keys with underscore (_) prefixes are not dumped. |
0x8 |
Include top-level keys with underscore prefixes. This bit tells XMLTracer that keys with underscore prefixes should be dumped in the top-level Dictionary or Order dictionary. Underscore-prefixed keys in descendent dictionaries are not traced. This bit has no effect unless it is used with the 0x4 bit. Note:
When this bit or the 0x10 bit is set, the prefixes in the dictionaries are temporarily changed, and then later reset to underscores. In the highly unusual case of a site using nonstandard dictionary prefixes to control DBStorage persistence, these flags will break the pipeline.
|
0x10 |
Include all keys with underscore prefixes. This bit tells XMLTracer that keys with underscore prefixes should be dumped recursively in the top-level dictionary and all descendent dictionaries. For example, you can use this bit to see all the keys set by the QueryCatalogInfo component in each line item dictionary. This bit has no effect unless it is used with the 0x4 and 0x8 bits. |
0x20 |
Include ContentList objects. This bit tells XMLTracer to include the contents of the _Discounts or _Content ContentList objects (for Basket and Content Selection Framework (CSF) pipelines respectively) in the trace. If this bit is not set, then the default behavior is to skip ContentList objects because they can be quite large. This bit has no effect unless it is used with the 0x4 and 0x8 bits. |
The following table shows flag values that result from using the logical OR operator to specify multiple flags.
Flag value |
Description |
|---|---|
0x4 |
Perform only minimal tracing. |
0xC |
Include top-level keys with underscore prefixes. |
0x1C |
Include all keys with underscore prefixes at all levels. |
0x2C |
Include top-level keys with underscore prefixes and include ContentList objects. |
0x3C |
Include all keys with underscore prefixes and include ContentList objects. |
You can use a –flags value of 255 (0xFF) to enable all trace levels. However, the XMLTracer component uses only the bit values listed above.
Values Written
XMLTracer writes output to files that you specify. It does not write any data to system dictionaries. For more information about the output from XMLTracer see Starting, Stopping, and Formatting XMLTracer Output.
Remarks
The XMLTracer component has the following limitations:
All objects in the dictionary that is being dumped must support the IPersistXML interface, which allows the contents of a Dictionary object to be persisted as an XML-formatted string in a specific format. This means that the Context dictionary cannot be dumped, because it typically contains an object such as ExpressionEvaluator()()() that doesn't support IPersistXML. Tracing a dictionary also fails if it contains a safearray with elements that are not variants.
When you specify the object to dump, it must be a Dictionary object. For example, you can't specify that you only want to dump the items from the SimpleList object in an Order dictionary. However, you can dump the items as part of the overall Order dictionary.
Currently there is no user interface for configuring values. You must set them by using dictionary keys in the Order dictionary as described in What Are the XMLTracer Configuration Options?
The traces can be very large, particularly if trace levels greater than 0x4 are used.