Symbol Support

  • Article

When correctly configured, Windows Performance Analyzer will show symbolic names from the symbol files for addresses found in the trace. Symbol decoding is particularly useful with sample profiling and context switches.

To decode symbols, the tools must be able to find the program database files, known as PDB files or symbol files, in order to build complete call stacks. PDB files are generated by the compiler and linker when a component is built. Microsoft provides the program database files for many of our products on-line in a symbol server. The Microsoft Debugging Tools for Windows and WPA use the on-line symbol server to look up symbol information. Note that this does require that the system you are using for analysis is connected to the internet. The xperf tools use the same symbol decoding infrastructure used by the Windows debugger, Windbg.exe. You can find more information on windbg and operating system symbols at the Debugging Tools for Windows - Overview topic on the WHDC Web site.

To configure symbol support, the environment variable _NT_SYMBOL_PATH needs to be defined. The following example sets the symbol path to use the Microsoft public symbol server with a downstream store in C:\symbols (please note that this is a single command line, it is shown on multiple lines here):

set _NT_SYMBOL_PATH= srv*C:\symbols*http://msdl.microsoft.com/downloads/symbols

The URL in the symbol path above specifies the on-line Microsoft symbol server. The path between the asterisks (C:\symbols) specifies the "down stream store". This is a local cache where the symbol resolution system keeps symbol files. The xperf tools will also decode symbols from components you develop. Simply add one or more paths to _NT_SYMBOL_PATH that contain the PDB files for the components being traced. For example, here is how the path was setup for the example above:

set _NT_SYMBOL_PATH=c:\coding\fs\release;srv*C:\symbols*

Enabling symbol decoding on the xperf command line is realizes using the top level command line parameter -symbols. For more information on symbol support with xperf enter the following command at the command prompt:

xperf -help symbols

Troubleshooting Symbol Decoding

The xperf trace symbol decoding support is quite complex. Please ensure the following requirements are met:

  • You have specified -symbols on the xperf command line, or selected "Load Symbols" in Performance Analyzer before opening a summary table.

  • You configured the environment variables as described in the online help:

    xperf -help symbols

  • The ETW kernel trace file has been stopped and merged properly. For more information see Stopping a Trace.

  • The ETW user trace file is processed by xperf or Performance Analyzer in conjunction with a kernel trace file taken in the same time on the same machine.

  • You have access to the binary and symbol sources specified on _NT_SYMBOL_PATH. If you use a symbol server, please note that many times the symbol server is just a redirector. If this is the case, you must have access to both the symbol server and the sites pointed to by the symbol server that are hosting the binaries and/or symbols. For more information please see Symbol Support.

  • Be sure _NT_SYMBOL_PATH points to the right files. If the files are from a different build or architecture they will not work. If the application binary files are not the same version as the symbols pointed to by _NT_SYMBOL_PATH you will not be able to view call stacks.

    To rule out a symbol mismatch, use symchk.exe from the Debugging Tools for Windows distribution to ensure the symbols match the binaries on the machine on which the trace was taken:

    symchk /v <local_file> /s <sympath_to_name.pdb>

    To rule out a binary mismatch, use fc /b to ensure the binaries on the machine on which the trace was taken match the ones on the drop share: fc /b <local_file> <drop_share_file>

  • The ETW kernel trace was captured with at least PROC_THREAD+LOADER. These flags provide basic information about process lifetime and image virtual address ranges in process memory, which are instrumental in decoding virtual addresses to images and symbols.

    To verify that these flags have been enabled in the ETW kernel trace, check that Process events (Create, Delete, Start Rundown, End Rundown) and Image events (Load, Unload, Start Rundown, End Rundown) are present in the table generated by:

    xperf -i kernel.etl -a tracestats -detail