Diagnostic tools for C++ developers

Article: dts0145

Applies to: dtSearch Engine Web

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 dtsErrorInfo structure, (2) debug logging to a text file, (3) generation of a stack trace when a program crashes, and (4) log files created in the index folder.

Error Reporting

Most of the dtSearch Engine's API functions involve a "Job" structure of some type (a dtsSearchJob, a dtsIndexJob, etc.). The Job structures all include an optional pointer to a dtsErrorInfo structure in the errorHandler member. After the job is done, the dtsErrorInfo will contain one or more strings and an error code for each error that occurred. A default dtsErrorInfo will just store these strings and codes as they are added, but a callback function can also be added to the dtsErrorInfo to provide immediate notification.

A simple example demonstrating use of a dtsErrorInfo:

dtsSearchJob searchJob;

dtsErrorInfo errorInfo;

searchJob.errorHandler = &errorInfo;

// ... set up searchJob ...

dtssDoSearchJob(searchJob, result);

// errorInfo will have a list of any errors that occurred

If you are using the C++ Support Classes included with the dtSearch Engine, an error handler is automatically attached to every job and is accessible through the job's GetErrorsWeb method. A FormatErrorsWeb method will generate a string containing the text of all errors that occurred during a job.

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 dtssDebugLogExWeb function. The prototype for dtssDebugLogEx is:

void dtssDebugLogEx(char *filename, long flags)

dtssDebugLogEx tells the dtSearch Engine to start recording a debug log in the specified file. The flags argument controls optional logging behavior.

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.

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

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. The functions to install and remove the crash handler are:

void dtssInstallCrashDiagnostics(dtsCrashHandlerInfo& info)

void dtssRemoveCrashDiagnosticsWeb

struct dtsCrashHandlerInfo {

long structSize;

void *pData;

void (*pNotifyFn)(void *pData, const char *logName);

char appName[40];

char appVersion[40];

char logName[256];

long reserved[5];

dtsCrashHandlerInfoWeb;

void copy(const dtsCrashHandlerInfo& other);

};

pData
An optional value to be passed to the pNotifyFn.

pNotifyFn
An optional callback function to be called when a crash occurs.

appName
appVersion
Information identifying the application, which will be written in the header of the log file.

logName
The name of the log file to create with the stack trace.

The stack trace file will list each item on the stack as an address. A utility included with the dtSearch Engine, StackTrace.exe, can be used to convert these addresses to symbol names. To use StackTrace.exe, you will need a .map file for your program. For example, if your program is MySearch.exe, you will need a map file named MySearch.map. The Visual C++ linker does not generate map files by default so you will need to enable this option to get a map file. Also, the map file is only valid for the particular build for which it was generated. If you modify and rebuild the program, a new map file will be needed. Once you have a map file and the text file created by dtssInstallCrashDiagnostics, you can get the symbols as follows:

StackTrace MySearch.map Error.txt > ErrorWithSymbols.txt

If your program includes multiple modules, you can list the map files for each module before the error file, like this:

StackTrace MySearch.map MyAdditionalDll.map Error.txt > ErrorWithSymbols.txt

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.

Both 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