Diagnostic tools for .NET developers

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.

Debug logging will not work if the process creating the log lacks write access to the folder containing the log file.

Flag	Effect
dtsLogTime	Each line in the log will have include the time, in hundredths of a second, since the start of execution.
dtsLogCommit	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.
dtsLogAppend	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 to generate a stack trace if an unhandled exception occurs during execution of the program.

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 in size 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:
https://support.dtsearch.com/webhelp/dtsearchCppApi/Monitoring_Index_Jobs.html