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.

Dd451523.alert_note(en-US,CS.90).gifNote:
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.

Dd451523.alert_note(en-US,CS.90).gifNote:
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.

See Also

Other Resources

Troubleshooting Pipelines

Pipeline Component Reference