Configure the symbol server or symbol path for LeanSentry diagnostics

LeanSentry Hang, CPU, Memory, and error diagnostics utilize Microsoft debugging and ETW profiling technologies under the covers to analyze production issues in a safe way.

These technologies rely on OS and application symbol files (PDBs) in order to perform code-level analysis. By default, LeanSentry configures standard Microsoft symbol servers to automatically retrieve the symbol files during the course of debugging.

However, you may want to explicitly configure the symbol path in order to achieve one of the following goals:

1. Speed up debugging (esp. if internet access or symbol server access is slow). 
2. Retrieve symbols from a company symbol server you have set up.  

How to configure the symbol path used by LeanSentry diagnostics

To configure the symbol path, open the environment settings for your environment:

1. Click "Show/hide environment settings"
2. Go to the "Other" tab
3. Scroll down to the "Debuggers" section:

You can then set the symbol path in the "symbol cache location" textbox and click "Save" to apply the settings.

Specifying the symbol path

The symbol path can be specified in two ways:

Using the standard Microsoft symbol path format.	For example: srv*https://msdl.microsoft.com/download/symbols Learn more about the Microsoft symbol path syntax.
Specifying a path to a directory where symbols should be cached.	For example: c:\symbols LeanSentry treats this as a path where symbols should be cached, and applies the following default symbol path: cache*c:\symbols;srv*http://referencesource.microsoft.com/symbols;srv*http://msdl.microsoft.com/download/symbols

Note that symbol path can contain environment variables, which are expanded by the LeanSentry Agent service before being passed on to the debugger.

Scenario 1: Specify a local cache directory where symbols should be cached

To make LeanSentry use a specific directory where all symbols should be cached, specify a path to that directory in the symbol cache location field, for example:

%temp%\symbols

During debugging the required symbols will be downloaded using the default Microsoft symbol servers and cached in the specified directory.

Scenario 2: Speed up debug processing by using a local-only symbol cache

In some cases, diagnostics may experience increased running times (and even timeouts) if the debugger has trouble downloading the symbols. This could happen if the internet connection is slow, the symbols for some DLLs are missing on the symbol server prompting failed download attempts, or there are very many symbols to be downloaded. 

In this case, it may be advantageous to disable symbol server access, and obtain all symbols from a local cache directory (and fail to resolve any symbols not already cached there).

To specify this behavior, specify this path in the symbol cache location field:

cache*%temp%\symbols

Note the "cache*" prefix before the directory. This causes LeanSentry to take this entire path as the symbol path, without adding the Microsoft symbol servers.

Scenario 3: Pre-generate a local symbol cache on the server

To enhance scenario #2 above of using a local-only cache for symbol access, you may want to pre-generate symbols that LeanSentry can use without having to download them.

To do this, you can use the symchk.exe tool found in the Windows Debugging tools directory on the server.

For example, to generate symbols for an IIS worker process running on the machine:

"C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\symchk.exe" /v /ie w3wp.exe /s "cache*C:\Users\leansentryagent\AppData\Local\Temp\symbols;srv*http://referencesource.microsoft.com/symbols;srv*http://msdl.microsoft.com/download/symbols" 

Place the path where you want symbols to be saved into the cache* part of the command above. For example, the path given above corresponds to the directory that would be used if you specified "%temp%\symbols" for the symbol cache directory.

Note that your path to symchk.exe may be different based on where your debuggers are installed, but they should commonly be installed in the "c:\Program Files\Windows Kits" or "c:\Program FIles (x86)\Windows Kits" directories.

Scenario 4: Use a custom symbol server

If you have a custom symbol server set up for your applications, you can specify it using the standard Microsoft symbol path syntax.

For example:

cache*%temp%\symbols;srv*http://symbols.mydomain.com/symbols;srv*http://referencesource.microsoft.com/symbols;srv*http://msdl.microsoft.com/download/symbols

Note that in this example, the debugger will first look for the symbols in the cache, then in your symbol server, then in the microsoft symbol servers in the given order. If the symbol is found, it will be stored in the local cache. 

The process for setting up your own symbol server is out of scope of this article; this is not something that you would do for LeanSentry, but rather something that you may already have in place.