How to run Backtrace to help diagnose issues with Enterprise Vault

Problem

Backtrace enables log files to be obtained that contain tracing information from Enterprise Vault processes in which the logging starts before a problem occurs. Unlike the Dtrace utility log files, a Backtrace log contains tracing information from a single process.

Backtrace retains tracing information in memory until a previously defined trigger event occurs. Backtrace then writes a limited amount of Dtrace information to a log file. The log file contains DTtrace information from before and after the trigger event occurred.

When Backtrace is enabled, the default is for it to create logs for all Enterprise Vault errors and warnings. This behavior can be modified by editing the Backtrace registry values.

If Dtrace is run, Enterprise Vault automatically disables Backtrace while Dtrace is running. 

NOTE: Changes to the Backtrace registry values take effect automatically, within a minute or so, and do not require a restart of any Enterprise Vault services/tasks. 

Solution

Warning: Incorrect use of the Windows registry editor may prevent the operating system from functioning properly. Great care should be taken when making changes to a Windows registry. Registry modifications should only be carried-out by persons experienced in the use of the registry editor application. It is recommended that a complete backup of the registry and workstation be made prior to making any registry changes.

 In order to enable and setup Backtrace, follow the steps below:

1. Edit the Backtrace registry values on the Enterprise Vault server that requires tracing.

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\KVS\Enterprise Vault\Backtrace

2. Change the Enabled (DWORD) value to 1 and click OK. Once Backtrace has been enabled, registry keys that are required are automatically created. To see these new keys refresh the registry page.

3. (Optional) To exclude a list of event ids from triggering Backtrace, change the RuleType (String) value to Exclude.

4. (Optional) Change the Exclude (String) value to a semicolon separated list of event IDs that Backtrace will ignore.

For example:

5. (Optional) To include a list of event ids that trigger Backtrace, change the RuleType (String) value to Include.

6. (Optional) Change the Include (String) value to a semicolon separated list of event IDs that Backtrace will include.

For example:

7. Reproduce the issue or error. Each Enterprise Vault process on the server maintains Backtrace information in memory. When a trigger event occurs, Backtrace writes trace information to a log file.

8. Change the Enabled (DWORD) value to 0 to disable Backtrace.

9. Collect the log file which is written by default to the Enterprise Vault Reports folder and send to technical support.

<%EVInstallDir%>\Reports\Backtrace\<YYYYMMDD>\
 

e.g. C:\Program Files (x86)\Enterprise Vault\Reports\Backtrace\20110531

The Backtrace log file names comprise the following items, separated by underscores:

■ The name begins with "EV".
■ Local date and time in the format YYYYMMDD_HHMMSSmmm
■ Server name. The name of the server on which the process is running.
■ Process name. The name of the process that is traced.
■ Process ID. The ID of the process that is traced.
■ Event IDs. The name contains a maximum of five IDs of the most recent events that are in the file.

The following example shows a log file name when error event 8938 from the Admin service triggers Backtrace on server MYSERVER. The trigger event 8938 is followed by error event 8942:

EV20110908_095919784_MYSERVER_AdminService(2872)_8938E_8942E.log

For additional information refer to the Backtrace chapter within the Utilities Guide.