Configuring the Registry

SymProxy stores its settings in this registry key.

HKLM/Software/Microsoft/Symbol Server Proxy

This registry key controls the location from which to find symbols to store in the Web site, the logging level, and whether or not SymProxy operates with a direct connection to the network. You can create this key by running the SymProxy registration tool (Symproxy.reg) provided with Debugging Tools for Windows. Type symproxy.reg at the command prompt or double-click it from Windows Explorer.

This will add entries for the settings that will be prefixed with an "x" so that they are disabled. To enable a setting, remove the "x" from in front of the desired setting.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy]
"Available Settings"="Remove the 'x' prefix to use the setting"
"xLogLevel"=dword:0000000f
"xNoInternetProxy"=dword:00000001
"xNoFilePointers"=dword:00000001
"xNoUncompress"=dword:00000001
"xNoCache"=dword:00000001
"xMissTimeout"=dword:00000e10
"xMissAgeTimeout"=dword:00015180
"xMissAgeCheck"=dword:00000e10
"xMissFileCache"=dword:00000001
"xMissFileThreads"=dword:00000010
"xFailureCount"=dword:00000004
"xFailurePeriod"=dword:00000078
"xFailureTimeout"=dword:00002d
"xFailureBlackout"=dword:0000384

The symproxy.reg registry file assumes a virtual directory name of Symbols and configures the Symbol Path to use the Microsoft Public Symbol Server.

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories]

[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Symbol Server Proxy\Web Directories\Symbols]
"SymbolPath"="https://msdl.microsoft.com/download/symbols"

The event logging entries in symproxy.reg are covered latter in the Event Log section of this topic.

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy]
"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}"
"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\
  00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\
  5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\
  00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00
"TypesSupported"=dword:00000007

The web directory entries in symproxy.reg are discussed in this topic.

Web Directories

For each virtual directory generated in IIS that you are using as a symbol store, you must setup a registry key below the Web Directories subkey of the following registry key.

HKLM/Software/Microsoft/Symbol Server Proxy

To edit the registry key for a symbol store virtual directory

  • Edit the contents of SymbolPath to contain all of the symbol stores used by the SymProxy symbol store. If there is more than one symbol store being used, separate them with semicolons. A maximum of 10 stores is supported for each value. HTTP paths must include the http:// prefix, and UNC paths must include the \\ prefix.

For example, if one of the virtual directories is called Symbols, and the symbols stores that it accesses are located at the UNC store \\symbols\symbols and the HTTP store https://msdl.microsoft.com/download/symbols, create the following registry key.

HKLM/Software/Microsoft/Symbol Server Proxy/Web Directories/Symbols

After this key is created, edit its SymbolPath to be \\symbols\symbols;https://msdl.microsoft.com/download/symbols. This can be seen in the following screenshot of the Registry Editor.

screen shot of the registry editor showing a revised symbolpath

In this example, SymProxy first searches for symbols in \\symbols\symbols. If the files are not found there, the Microsoft Symbol Store will be used.

  • In each of the keys under Web Directories that match the Virtual Directory names, a REG_SZ called SymbolPath needs to be created. The value contains all the upstream symbol stores that will be used to populate the SymProxy symbol store.

  • A maximum of 10 entries are supported.

  • Separate entries with semicolons.

  • UNC paths need to include the “\\” prefix

  • HTTP paths need to include the “http://” prefix

  • Order the values from least expensive to most expensive.

    • You will need to balance usage performance goals vs. server and data communications costs in the calculation.

    • In general, put local SMB/HTTP servers before internet HTTP servers.

SymProxy Performance Counters

SymProxy can emit performance counters via a provider called SymProxy.

To enable the performance counters support, register the symproxy manifest file in an administrator command window:

C:\> lodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man

To disable the performance counters support, unregister the manifest:

C:\> unlodctr.exe /m:%WINDIR%\system32\inetsrv\symproxy.man

SymProxy Event Tracing for Windows

SymProxy can create ETW events via a provider called Microsoft-Windows-SymProxy.

C:\> logman query providers | findstr SymProxy
Microsoft-Windows-SymProxy {0876099C-A903-47FF-AF14-52035BB479EF}

To enable the ETW support, register the manifest file:

C:\> wevtutil.exe install-manifest %WINDIR%\system32\inetsrv\symproxy.man

To disable the ETW support, unregister the manifest file:

C:\> wevtutil.exe uninstall-manifest %WINDIR%\system32\inetsrv\symproxy.man

Event Log

If ETW is configured, the events are recorded as events in the Operational and Analytic channels under Applications and Services Logs\Microsoft\Windows\SymProxy in the Event Log.

To correctly view the message of the Event Log entries, the Event Log area of the symproxy.reg file needs to be added to the registry:

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\EventLog\Application\Microsoft-Windows-SymProxy]
"ProviderGuid"="{0876099c-a903-47ff-af14-52035bb479ef}"
"EventMessageFile"=hex(2):25,00,53,00,79,00,73,00,74,00,65,00,6d,00,52,00,6f,\
  00,6f,00,74,00,25,00,5c,00,73,00,79,00,73,00,74,00,65,00,6d,00,33,00,32,00,\
  5c,00,69,00,6e,00,65,00,74,00,73,00,72,00,76,00,5c,00,53,00,79,00,6d,00,50,\
  00,72,00,6f,00,78,00,79,00,2e,00,64,00,6c,00,6c,00,00,00
"TypesSupported"=dword:00000007

SymProxy Events

SymProxy logs the following events:

Event ID Description Channel
1 Start of the ISAPI filter Admin
2 Stop of the ISAPI filter Admin
3 Configuration of the ISAPI filter Admin
4 Miss Cache Statistics Admin
10 URL Request - Local Cache Hit Operational
11 URL Request - Local Cache Miss Operational
20 Symbol Download via SymSrv Operational
30 Critical Symbol Missing Admin
31 Critical Image Missing Admin
40 SymSrv – Path Not Found Admin
41 SymSrv – File Not Found Admin
42 SymSrv – Access Denied Admin
43 SymSrv – Path Too Long Admin
49 SymSrv – Error Code Admin
90 Lock Contention Operational
100 General Critical Message Analytic
101 General Error Message Analytic
102 General Warning Message Analytic
103 General Informational Message Analytic
104 General Analytic Message Analytic
105 General Debug Message Debug

Symbol Server Proxy Configuration

SymProxy stores its configuration settings in the following registry key area:

HKLM/Software/Microsoft/Symbol Server Proxy

From this location, SymProxy acquires its global settings and the symbol paths of upstream symbol stores.

You can create this key by merging in the symproxy.reg file you customized as discussed earlier.

Symbol Server Proxy’ key

The Symbol Server Proxy registry key supports the following global settings (all REG_DWORD). Settings can be applied live by recycling the application pool. A new w3wp.exe process will be created and it will read the new values. Once all pending requests to the old w3wp.exe process have completed, the old w3wp.exe process will end. IIS by default recycles w3wp.exe processes every 1,740 minutes (29 hours).

REG_DWORDl Description
LogLevel

By default, SymProxy doesn’t log an extensive amount of information about its use of SymSrv.dll. Creating REG_DWORD:"LogLevel " with a value of 5 (Analytic) or 6 (Debug), enables the additional logging.

NoInternetProxy

When running as a service, SymSrv.dll uses WinHTTP instead of WinInet to make HTTP requests. Consequently, you may need to set up HTTP proxy settings so that the service can access outside network resources. You can do this using the netsh program. Type “netsh.exe winhttp -?” for instructions.

By default, SymProxy uses the designated HTTP proxy. If no HTTP proxy is configured, SymProxy will use a dummy proxy. This allows secure access to HTTP sites within your intranet. As a side effect, this prevents SymProxy from directly connecting to non-secure sites.

Creating the REG_DWORD:"NoInternetProxy" value configures SymProxy to operate without a proxy, allowing a direct connection.

NoFilePointers

By default, for symbols that don’t exist, SymProxy will look for a file.ptr file next to the requested file (in the local cache). If found, it will return the location specified by the file.ptr file. This ability is only required when the local cache is being populated by SymStore.exe.

Create the REG_DWORD:"NoFilePointers" value to skip the lookup.

NoUncompress

By default, SymProxy will decompress downloaded symbols before returning the file to the caller. This reduces CPU at the client, but increases I/O.

Create the REG_DWORD:"NoUncompress" value to skip the decompression.

NoCache

By default, SymProxy will cache downloaded symbols to the local file system, defined by the virtual directory’s path.

Create the REG_DWORD:"NoCache" value to skip the download and to provide the remote path of the file to the client instead.

MissTimeout

Timeout period, in seconds, for which missing symbols are reported as missing without re-querying the upstream symbol servers.

A miss is associated with a UTC based time. Subsequent requests for the file are immediately rejected for N seconds.

The first request for the file after N seconds causes the upstream symbol stores to be re-queried.

On success, the symbol file is returned and the miss is deleted.

On failure, the miss is moved forward to the current time (in UTC) to start a new timeout period.

Use the “Miss Cache ” counters to monitor the misses.

• Unspecified - (default) 300 seconds/5 minutes

• 0 – Feature disabled

• N – Timeout lasts N seconds

MissAgeCheck

Period between Miss Age checks. The Miss cache is scanned and records older than MissAgeTimeout seconds are removed.

The current statistics are saved to the Event Log using Event ID 4.

• Unspecified - (default) 3600 seconds / 1 hour

• 0 – Feature disabled

• N – Period between checks in N seconds

MissFileCache

By default, SymProxy does not save miss information to disk. Create the REG_DWORD:"MissFileCache" value to cache miss information in the symbol folder tree. Create the REG_DWORD:"MissFileCache" value to cache miss information in the symbol folder tree.

Enable MissFileCache when miss informarion needs to be shared across an IIS farm. Enabling MissFileCache also makes worker process recycling more efficient.

MissFileCache causes an I/O operation on the first request for a missing symbol (Miss File Read), the download of a symbol (Miss File Delete), and a failed symbol lookup (Miss File Write).

Use the “Miss File XXX/sec” counters to monitor the operations.

It is safe to delete .miss files while the SymProxy is running:

C:> del C:\SymStore\Symbols\.miss /s

MissFileThreads

By default, SymProxy performs up to 16 concurrent asynchronous file I/O operations for the Miss File feature. Creating the REG_DWORD:" MissFileThreads" value overrides the default limit. Values can be between 1 and 64.

Use the “Miss File Queue Depth” counter to monitor the load.

FailureTimeout

FailureCount

FailurePeriod

FailureBlackout

The Blackout feature is used to termporarly disable upstream symbol stores that are unresponsive. The Blackout feature uses 4 REG_DWORD values to define the behaviour. By default, the feature is disabled.

For each upstream symbol store defined in a Symbol Path, failures are individually recorded. If a request takes longer than FailureTimeout (msec), the failure count is incremented.

The Symbol Path is marked as dead after FailureCount failures in FailurePeriod seconds. At this time, all requests are ignored until FailureBlackout seconds have elapsed. The first caller after the timeout tests the upstream symbol store. On success, the timeout is removed and requests are allowed. On failure, the time is set to Now+FailureBlackout seconds. After that time, the upstream symbol store is tested again.

Accessing Outside Network Resources

When SymSrv is used in conjunction with SymProxy, it runs as a service and uses the WinHTTP API to access symbols over an HTTP connection. This differs from its usual behavior of using WinInet for this purpose.

Consequently, you may need to set up HTTP proxy settings so that this service can access outside network resources. Use one of the following methods to configure these settings:

  • In Windows Vista, Windows Server 2008, and later versions of Windows, use the Netsh tool (netsh.exe). For instructions, type the following in a Command Prompt window: netsh winhttp -?

The default behavior of SymProxy is to use whatever HTTP proxy is designated by either ProxyCfg or Netsh. If no HTTP proxy is configured, SymProxy uses a dummy proxy to allow access to secure HTTP sites within your intranet. As a side effect, this technique prevents SymProxy from working with direct connections to the external Internet. If you wish to permit SymProxy to operate with a direct connection to the Internet, create a REG_DWORD value named NoInternetProxy in the Symbol Server Proxy key of your registry. Set the value of NoInternetProxy to 1 and verify that there is no HTTP proxy indicated by ProxyCfg.

Send comments about this topic to Microsoft