Diagnostic tools for .NET developers

Last Reviewed: March 16, 2013

Article: DTS0196


Applies to: dtSearch Engine 6.4 and later

The dtSearch Text Retrieval Engine includes several diagnostic tools to help isolate problems that arise during execution of a program. These include: (1) detailed error reporting through the JobErrorInfo object, (2) debug logging to a text file, and (3) generation of a stack trace when a program crashes.

dtSearch indexes also contain several text files that can provide useful diagnostic information.

Error Reporting

Most of the dtSearch Engine's API functions involve a "Job" structure of some type (a SearchJob, an IndexJob, etc.). After a Job has been executed, the Errors property of the job will contain a JobErrorInfo that provides the text and error codes of each error that occurred. Documentation on the meaning of the error codes appears in the "Error Codes" topic in the dtSearch Engine help file.

Debug Logging

dtSearch Engine can generate a debug log that provides detailed information about internal processing of an API call. To enable debug logging in the dtSearch Engine, call the SetDebugLogging method of the Server object.

SetDebugLogging(LogName as String, flags as Long)

SetDebugLogging tells the dtSearch Engine to start recording a debug log in the specified file. The flags argument controls optional logging behavior. To turn off debug logging, call SetDebugLogging with a blank LogName.

Note:  Debug logging will not work if the process creating the log lacks write access to the folder containing the log file.   For example, an ASP application running inside IIS may not be permitted to write to some folders.  If SetDebugLogging does not seem to work,

(1) Create an empty folder with a simple name like c:\log

(2) Right-click the c:\log folder in Windows Explorer and select "Permissions"

(3) Set the permissions for c:\log to grant "Everyone" "Full Control" access

(4) Use c:\log\debuglog.txt as the name of the log file





Each line in the log will have include the time, in hundredths of a second, since the start of execution.


The log will be committed to disk after each line is written. This slows execution considerably but ensures that the log will survive a system crash.


Log data is appended to the file if it already exists. Otherwise the file will be overwritten.

Crash Diagnostics

The dtSearch Engine can set up a crash handler so that if a General Protection Fault or other unhandled exception occurs during execution of the program, a stack trace file will be created.

To set up a crash handler, call SetDebugLogging with the dtsCrashLog flag and no other flags, like this:

Server.SetDebugLogging "c:\error.txt", dtsCrashLog

After a crash occurs, the text file will contain a stack trace file identifying the state of the calling program and the dtSearch Engine when the crash occurred.

Index Log Files

After an index update completes, the file indexlog.dat in the index folder will contain a text record of what happened during the index update.   The log includes IndexJob settings, the dtSearch Engine build number, the start and end times, the option settings in effect, and a summary of the number of files indexed, size of the index, etc.  The indexlog.dat file will also contain a list of files that could not be indexed, along with a diagnostic message for each file.

The file history.ix contains a chronological record of every index update, similar to the indexlog.dat file but without the list of files that could not be indexed.  The history.ix file is limited to about 512k, so it will include only the most recent updates for indexes that have been updated many times.

Exceptions.ix, if present, will record any serious errors that occurred during indexing such as low-level I/O errors.

All log files are in text format (the encoding is UTF-8).

dtSearch Desktop creates additional HTML log files, Index_LastUpdateErrors.htm and Index_LastUpdateSummary.htm.  The information needed to generate this log is obtained from the index status monitoring APIs, which are documented here: