Load Symbols or Configure Symbol Paths

In Windows Performance Analyzer (WPA), you can set a recording to load symbols or change symbol paths.

To set a recording to load symbols

• On the Trace menu, click Load Symbols.

NoteВ В When you click Load Symbols, a progress bar (along with a count of the symbols found) above the Graph Explorer windows and the Analysis tab. In addition, on the graph itself, the data areas become grayed-out and a progress bar displays in each data area.

To change symbol paths

On the Trace menu, click Configure Symbol Paths. By default, the dialog opens on the Paths tab

Enter or select the desired paths, and then click OK.

To cache symbol files to a SymCache folder

On the Trace menu, click Configure Symbol Paths. By default, the dialog opens on the Paths tab.

Click SymCache. All stored files (with their corresponding paths) display in the body of the SymCache tab, which you can scroll to find specific SymCache file paths.

NoteВ В Invalid paths display in red.

Select SymCache generation folder and then click the Browse for Folder icon to search for the location where your SymCache files are stored, and then click OK on the Browse for Folder dialog.

Select each SymCache path to save to the SymCache generation folder specified in the previous steps, and then click OK.

Select each SymCache path to save to the SymCache generation folder specified in the previous steps, and then click OK.

To change load settings when configuring symbols

On the Trace menu, click Configure Symbol Paths. By default, the dialog opens on the Paths tab.

Click Load Settings.

Select how you want to load symbols based on the following options:

• Load symbols after load
• Load symbols per the following restrictions:

NoteВ В When selecting the Load symbols per the following restrictions: option, you can specify whether you want to load symbols for specifi processes or you can choose to not load symbols for specific images. You can opt to specify restrictions for both processes and images.

Loading Symbols

You can set the following user preferences in WindowsВ Performance Analyzer (WPA):

Load Symbols

Configure Symbol Paths

To change these options, open a recording and then select the option on the Trace menu.

Managed Symbols

Symbol resolutions and stacks for managed processes are supported on the following systems:

With .NET Framework 4.5 or a later release on WindowsВ 8 or later release

With .NET Framework 4.0 or a later release on x86 machines

When you capture a trace by using WPR, WPR enables all providers that are required to resolve managed symbols in the trace. WPR creates a folder next to the saved trace that contains PDB files of these managed symbols. When WPA opens the trace, WPA looks for this folder and automatically adds it to the symbol path. If WPR was not used to generate the trace, any symbols for .NET Framework programs might not decode completely or decode at all.

JavaScript symbols

Symbols resolution and stacks for JavaScript processes are supported on systems that are running the following software:

WindowsВ 7 together with Internet ExplorerВ 10 or later version

Applications that use JavaScript on WindowsВ 8

WP enables the required providers to decode symbols for JavaScript code on supported systems. The JavaScript method addresses and stack frames will decode to a JavaScript file name, method name, line number and column number.

Relative Paths and Embedded Environment Variables

The _NT_SYMBOL_PATH and _NT_SYMCACHE_PATH environment variables can use relative paths, absolute paths, network share paths, or embedded environment variables. WPA converts relative paths to absolute paths when you first set the relative paths. WPA converts relative paths that WPA loads from environment variables when the program starts.

WPA converts relative paths that you enter in the Configure Symbol Paths dialog box when you close the dialog box. Changes to the current directory do not affect relative paths that you have already set. The Configure Symbol Paths dialog box shows the currently set paths when you first open the dialog box so that you can see the way that WPA expanded any relative paths.

WPA expands embedded environment variables at the same time that it expands relative paths. Because WPA captures environment variables when the program starts, changes to the environment variables that are outside a currently running instance of WPA do not appear in that instance.

Other programs that use the _NT_SYMCACHE_PATH environment variable, such as WinDbg or Microsoft Visual Studio, might not handle relative paths or embedded environment variables in the same way.

SymCache Path

WPA uses SymCache files to cache symbol information from program database (PDB) files in a way that is compact and easy to access. After WPA populates a SymCache folder with the symbols for a trace, reloading the symbols for that trace is much faster. If a SymCache file becomes too large or is no longer needed, you can safely delete that SymCache file. WPA repopulates the SymCache folder with new files as needed. You can also copy SymCache files to another computer or share the files over a network to expedite symbol loading on different computers.

If you use the Configure Symbol Paths dialog box to set the _NT_SYMCACHE_PATH environment variable to a folder that WPA cannot access, the OK button does not close the dialog box. However, you do not receive an error message.

If the _NT_SYMCACHE_PATH environment variable is unassigned or empty, WPA creates a SymCache folder at the root of the drive that contains the WPA executable file. If the _NT_SYMCACHE_PATH environment variable is running on a network share, the variable creates a SymCache folder at the root of the drive that contains the Program Files folder. This is usually drive C.

SymCache Examples

The following command puts the SymCache file in the C:\SymCache folder:

The following command puts the SymCache file in the C:\SymCache folder, searches the \\network\SymCache folder for symbols, and then processes the _NT_SYMBOL_PATH environment variable:

This example copies any symbols that the example finds in the \\network\SymCache folder into the C:\SymCache folder. This enables the user to create a large SymCache folder and then copy only the files that the user needs for a specific trace into the designated folder.

To search multiple alternative SymCache folders, append the folders to the search path by using an asterisk (*) separator. When WPA finds a SymCache file in one of the alternative locations, WPA copies the file only to the first SymCache folder in the path. WPA also puts newly created SymCache files into the first SymCache folder in the path.

To disable copying and writing but still use the hierarchical search feature, you should leave the first position in the path empty, as shown in the following example:

When you issue this command, WPA searches the \\network\SymCache folder. However, WPA does not copy the results or write the generated SymCache files to a different folder.

Symbol Path

For basic information about the _NT_SYMBOL_PATH environment variable, see the following MSDN articles:

Symbol loading in WPA depends on the paths that the _NT_SYMBOL_PATH environment variable specifies (excluding symbols that WPA has already cached in the SymCache folder). WPA searches the paths sequentially, starting on the left. However, loading symbols from a PDB file in one of these paths can be time-consuming, especially if the PDB exists on a remote computer. We therefore recommend that you put network paths after any local paths and that you use a local PDB cache for any remote symbol server. However, even if all the symbols are stored locally, WPA can become unresponsive during the time that it loads symbols. WPA returns to an interactive state after it finishes loading symbols.

When the _NT_SYMBOL_PATH environment variable is not set, WPA uses the following default value:

The semicolons (;) separate the different paths. The first path is the period (.). WPA maps this path to the current folder when WPA loads the trace. See the SymCache Path section of this article for more information about the way that WPA processes relative paths.

The second path is the following:

You must also set the NGEN PB path:

When you specify this path, WPA downloads symbols from the Microsoft public symbol server and caches the PDB files in the \Symbols folder (this folder is relative to the Windows Performance Toolkit installation folder).. Therefore, WPA puts the Symbols folder next to the SymCache folder. However, if the SymCache folder is on a network share, WPA creates the Symbols folder at the root of the drive that holds the Program Files folder. This is usually drive C.

If you do not want to search and load symbols from PDB files, you can set the _NT_SYMBOL_PATH environment variable to a local folder that does not contain symbols, such as a period (.). Do not leave the _NT_SYMBOL_PATH environment variable empty. If you leave the _NT_SYMBOL_PATH environment variable empty, WPA uses the default.

Symbol Support

When Windows Performance Analyzer (WPA) is correctly configured, WPA shows symbolic names from the symbol files for addresses that are found in the recording.

To decode symbols, the tools must locate the program database files, known as program database (PDB) files or symbol files, to build complete call stacks. The compiler and linker generate PDB files when the system builds a component. Microsoft provides the program database files for many Microsoft products in an online symbol server. The Microsoft Debugging Tools for Windows and WPA use the online symbol server to look up symbol information. Therefore, the computer must be connected to the Internet if the symbol files are not copied locally. The Windows Performance Toolkit uses the same symbol decoding infrastructure as the Windows debugger, Windbg.exe. For more information, see WinDbg.

To configure symbol support, you must define the _NT_SYMBOL_PATH environment variable. The following example sets the symbol path to use the Microsoft public symbol server together with a downstream store in C:\symbols:

Note that this example is a single command line.

The URL in this symbol path specifies the online Microsoft symbol server. The path between the asterisks (C:\symbols) specifies the downstream store. This is a local cache in which the symbol resolution system keeps symbol files. WPA Tools also decode symbols from components that you develop. Add one or more paths to _NT_SYMBOL_PATH that contain the PDB files for the components that you want to record. For example, the following example shows how the path was set up for the previous example:

When Xperf or WPA decodes symbols, Xperf or WPA caches a condensed version of the original symbol files, or PDBs, on disk in the \symcache directory. To do this, Xperf or WPA uses the symbols that are available at the time. The operating system symbols that are available outside Microsoft are public symbols. These symbols contain less information than internal private symbols. In black-box testing, public symbols can also include incorrect information. Private symbols, which are more reliable, can be obtained under non-disclosure agreements. If a user has decoded a recording by using public symbols, and the user then obtains private symbols, the user must clear the \symcache directory before Xperf or WPA can discover the new private symbols.

Troubleshooting Symbol Decoding

Symbol decoding support is complex. The following requirements must be met:

You must specify -symbols on the Xperf command line or select Load Symbols on the Trace menu in WPA after you open a recording.

The environment variables must be configured correctly. For more information for Xperf, see symbols.

The ETW kernel recording file must have been stopped and merged correctly. For more information, see Stopping a Recording.

Windows Performance Recorder (WPR) or WPA merges the ETW user recording file together with a kernel recording file that is taken at the same time on the same computer.

You must have access to the binary and symbol sources that _NT_SYMBOL_PATH specifies. If you use a symbol server, the symbol server is often just a redirector. In this case, you must have access to both the symbol server and the sites that the symbol server points to that host the binaries and symbols.

_NT_SYMBOL_PATH must point to the correct files. If the files exist from a different build or architecture, the files will not work. If the version of the application binary files is not the same version as the symbols that _NT_SYMBOL_PATH points to, you cannot view call stacks.

To rule out a symbol mismatch, use Symchk.exe from the Debugging Tools for Windows distribution to ensure that the symbols match the symbol files on the computer on which the recording was taken. For example:

To rule out a binary mismatch, use the fc /b command to ensure that the binaries on the computer on which the recording was taken match the binaries on the drop share. For example:

In Xperf, you must capture the ETW kernel recording by using at least the PROC_THREAD+LOADER flags. These flags provide basic information about process lifetime and image virtual address ranges in process memory. This information helps XPerf to decode virtual addresses to images and symbols.

To verify that these flags have been enabled in the ETW kernel recording, check that Xperf -process events (Create, Delete, Start Rundown, End Rundown) and Image events (Load, Unload, Start Rundown, End Rundown) are present in the table that is generated by using the following command:

NoteВ В All of these events might not be listed in the table, depending on whether these events occurred.

Limitation in Xperf Symbol Decoding

Xperf defaults to the system drive if a drive is not specified for an executable image (such as \Path\Library.dll). When you run the -d/-merge command, if Xperf cannot find an executable image that existed in a running process during the recording, Xperf cannot retrieve the corresponding image and symbol file identity information and add the information to the merged recording. Without that information, Xperf cannot perform symbol decoding for that image in that recording.

This issue does not affect other file paths, such as the paths in disk I/O or file I/O.

To enable symbol decoding and to help enable correct image load and unload paths in Xperf ETW recordings, you should store all executable images for which you might require symbol decoding or image load and unload paths on the system drive. Then, run the images from that drive. If that is not possible, create a mirror of the images on the system drive, even if you run the images from another drive. For example, if C: is your system drive, create an identical copy of D:\game\bin\binkw32.dll at C:\game\bin\binkw32.dll.