Crash Reporting

Along with logging, crash dumps and Node.js diagnostic reports are an important source of information to help diagnose the cause of fatal errors in Web app backends, services, and agents. Such reports are disabled by default. They require careful handling, since they may contain sensitive information about the program. As long as adequate security can be maintained, it is recommended that a backend program should enable both crash dumps and Node.js diagnostic reports. Here is a description of how to do that.

Opting into Crash Reporting

To opt into crash dumps and/or Node.js diagnostic reports, the backend program must:

• Define the IModelHostConfiguration.crashReportingConfig property when configuring IModelHost.
• The crashDir property must be set.

See CrashReportingConfig for all of the options.

Native-Code Crashes

An unhandled exception in the native-code portion of @itwin/core-backend or any addon will cause the backend program to terminate prematurely. The backend can cause a crash dump to be written in such an event. A crash dump contains information about what native code was running at the time of the crash, including native call stacks for all threads, and may also contain a copy of the contents of memory.

To opt into crash dumps, the backend program must:

• Set the IModelHostConfiguration.crashReportingConfig.enableCrashDumps to true.

Unhandled Exceptions and Other Fatal Errors

An unhandled exception or a fatal error such as running out of memory will cause the backend program to terminate prematurely. The backend program can enable Node.js Diagnostic Reporting to generate a report in case of these events. A diagnostic report file is a JSON file that includes native-code and Javascript call stacks, plus other information about the state of the session. See https://nodejs.org/api/report.html for details.

To opt into Node.js Diagnostic Reporting, the backend program must:

• Set IModelHostConfiguration.crashReportingConfig.enableNodeReport = true

Uploading Reports

Crash dump and/or Node.js diagnostic report files will be written to the directory specified by the IModelHostConfiguration.crashReportingConfig.crashDir directory. If you can access that location directly, that may be enough. You can check that directory periodically to detect crashes.

You may also supply a script to process dump and Node.js diagnostic report files. See IModelHostConfiguration.crashReportingConfig.dumpProcessorScriptFileName. Typically, this script would upload the specified file to a crash dump service for further analysis and reporting.

If you set IModelHostConfiguration.crashReportingConfig.uploadToBentley, then all dump and Node.js diagnostic report files will be uploaded to and stored in Bentley's crash-reporting service.

Example Code

// Enable both crash dumps and node-report. Write reports to d://customdumpdir on Windows
hostConfig.crashReportingConfig = {
  crashDir: (process.platform == "win32")? "d:\\customdumpdir": "/tmp";
  writeDumpsToCrashDir: true,
  writeNodeReportsToCrashDir: true,
};

IModelHost.startup(hostConfig);