Share via


Loading Symbols

Applies To: Windows 8, Windows 8.1

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.

In this article:

  • Managed Symbols

  • Relative Paths and Embedded Environment Variables

  • SymCache Path

  • Symbol Path

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:

C:\SymCache

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:

C:\SymCache*\\network\SymCache

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:

*\\network\SymCache

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:

 .;SRV*\Symbols* http://msdl.microsoft.com/download/symbols;

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:

 SRV*\Symbols* http://msdl.microsoft.com/download/symbols

You must also set the NGEN PB path:

set _NT_SYMBOL_PATH=srv*C:\Symbols.NGEN;srv*http://msdl.microsoft.com/download/symbols

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.

When WPA opens a recording, WPA looks for a folder that has the same name as the trace that uses the .ngenpdb extension. If WPA finds this folder, WPA appends the folder to the end of the _NT_SYMBOL_PATH environment variable. Windows® Performance Recorder (WPR) automatically creates a folder that contains PDB files for managed code that WPR captured during the recording. For example, if you open the C:\trace.etl recording in WPA, WPA searches for the C:\trace.etl.ngenpdb folder. If this folder exists, WPA adds the folder to the _NT_SYMBOL_PATH environment variable.

See Also

Tasks

Load Symbols or Configure Symbol Paths

Reference

Missing Symbols

Other Resources

WPA Features
Using CLR 4.0 NGEN PDB Support