Using MFTrace

MFTrace is a tool for generating trace logs for Microsoft Media Foundation applications.

MFTrace uses the Detours library to hook into Media Foundation API calls and generate trace logs. MFTrace can also record traces from any component that uses Event Tracing for Windows (ETW) or the software trace preprocessor (WPP) to generate traces. Trace logs can be generated by starting a new process from MFTrace, or by attaching MFTrace to an existing process.

Usage

mftrace [-a Process][-c ConfigurationFile][-dc][-es][-k KeyWords][-l Level][-o OutputFile][-v][-?] [{COMMAND|ETL_FILE}]

Command-line arguments	Description
-aProcess ID or Process Name	Attach to a running process.
-cConfiguration File	Read settings from the specified configuration file. See MFTrace Configuration File.
-dc	Disable tracing for child processes. By default, tracing is enabled for child processes.
-es	Enable public symbols.
-kKeywords	A comma-separated list of keywords. See MFTrace Keywords.
-lLevel	The trace level. 0: None 1: Critical 2: Error 3: Warning 4: Informative 5: Verbose 16: Debug
-oOutput File	Write the trace output to the specified file. By default, output goes to stdout. If an output file is specified, the file name extension must be one of the following: .etl: Event trace log (ETL) file. .log or .txt: Text file.
-v	Enable verbose mode.
-?	Display usage information.
COMMAND	Command-line arguments to create a new process.
ETL_FILE	The name of an existing ETL file. If this argument is provided, the ETL file is converted to text output.

 

Environment Variables

TRACE_FORMAT_SEARCH_PATH

To trace components that use the Windows software trace preprocessor (WPP), set this environment variable to the specify the path to the trace message format (TMF) files for the component.

_NT_SYMBOL_PATH

If symbol lookup is enabled (-es), set this environment variable to specify the symbol path.

Examples

Create a new process and trace that process:

mftrace.exe wmplayer.exe Wildlife.wmv

Attach MFTrace to an existing process:

mftrace.exe -a wmplayer.exe
mftrace.exe -a 9132

Send trace output to a text file:

mftrace.exe -a wmplayer.exe -o trace.txt

Trace ETW or WPP events:

mftrace.exe -c config.xml -o trace.txt
mftrace.exe -c config.xml -o trace.etl

Note

The first example generates a text file. The second example generates an ETL file.

 

Convert an ETL file to a text file:

mftrace.exe -o trace.txt trace.etl

Remarks

By default, MFTrace generates only Detours traces. To generate ETW or WPP traces, you must provide a configuration file. The configuration file gives the names of the trace providers. For more information, see MFTrace Configuration File.

MFTrace can send output to the following destinations:

• stdout (the default).
• A text file.
• A binary ETL file.

If you are logging ETW/WPP traces, an ETL file is the most efficient option, because the trace data are saved as binary blobs. After the trace session is complete, you can use MFTrace to convert the ETL file to a text file.

Note

For Detours tracing, text output is just as efficient as an ETL file. Therefore, if you log only Detours traces (with no ETW/WPP traces), text output is recommended.

 

For Detours tracing, you must attach MFTrace to a running process (-a) or use MFTrace to create a new process. For ETW/WPP traces, MFTrace listens to any event provider that is listed in the configuration file.

You can filter the trace results by specifying trace keywords, either through the -k command-line option, or in the configuration file. The more typical usage, however, is to log all traces and then use a script or grep to search for particular string patterns.

Interpreting the Trace Results

You can use MFTrace to answer questions about what happens inside your Media Foundation application or component. The following table lists some typical questions. The second column gives the search string that can help answer the question.

Question	Search strings
Did an error occur?	"0xc00d"
Did the topology resolve correctly?	"CTopologyHelpers::Trace"
Did the Media Session start?	"MESessionStarted"
Which file was played?	"CMFSourceResolverDetours"
What are the media types for the source streams?	"New stream", "MENewStream", "CMFMediaSourceDetours::TracePD"
Did the source streams generate samples?	"CMFMediaStreamDetours::HandleEvent", "MEMediaSample"
Did playback reach the end of the data?	"MEEndOfStream", "MEEndOfPresentation"
Did the format change?	"MEStreamFormatChanged" (media sources), "New format", "MESessionStreamSinkFormatChanged" (media sinks)
What objects were created?	"COle32ExportDetours::CoCreateInstance"
Did the Media Foundation Transforms (MFTs) in the pipeline process any data?	"CMFTransformDetours::ProcessOutput", "CMFTransformDetours::ProcessInput"
What states were set on the MFTs?	"CMFTransformDetours::ProcessMessage"
Did an MFT request input data?	"MF_E_TRANSFORM_NEED_MORE_INPUT" (synchronous MFT), "METransformNeedInput" (asynchronous MFT).
Did an asynchronous MFT produce output data?	"ProcessOutputs available"
Did a media sink request samples?	"MEStreamSinkRequestSample"
Did a media sink receive samples?	"CMFStreamSinkDetours::ProcessSample"
DirectShow: Which samples were processed?	"sample", "CMemInputPinDetours"
DirectShow: What filter graph was used?	"CGraphHelpers::Trace"
Were there multiple processes?	"CreateProcess" Note: Also look for the process identifier, which appears at the start of every trace line.

 

Related topics

MFTrace