This is "Exceptions" page in EurekaLog project's options.

Exceptions options

Chained/Nested exceptions

Chained exception is an exception which occurs during handling of another exception. That "another" (original) exception is called "nested exception". For example:

try

  raise ERangeError.Create('Invalid item index'); // <- low-level error (a.k.a. original, first, bottom, inner, nested, root)

except

  raise EFileLoadError.CreateFmt('Error loading file %s', [FileName]); // <- high-level error (a.k.a. introduced, last, top, outer, chained)

end;

Note: for more information about nested/chained exceptions - see this article.

As you can see, low-level exception is the exception you're interested in. It indicates a reason for failure. This is what you typically want to be logged. Chained exception is triggered by original exception and provides more descriptive error message. So, you typically want to show it to user as error message. Thus, typically you want first exception to be logged, but last exception to be shown to end user.

Classic/default Delphi and C++ Builder behavior is to work only with last exception always.

Delphi 2009+ only: starting with Delphi 2009 - there were new features introduced to exceptions in RTL. Support for chained exceptions was added. There are new properties BaseException and InnerException as well as special raising construct. In this model, you need to use RaiseOuterException or ThrowOuterException to preserve original exception when raising new exception. EurekaLog implements similar model with the same properties, except it doesn't require you to use special raising construct. Any exception raising automatically saves previous (original) exception in InnerException property. This feature available on all supported IDE versions.

Options on "Nested exceptions" page allow you to customize EurekaLog behaviour related to nested/chained exceptions.

Important note: this feature require EurekaLog to be able to track life-time of exception objects. Therefore, it's highly recommended that you enable the following options:

Otherwise it's recommended that you keep all options on this page into "Classic" position, or EurekaLog may show information about wrong exceptions.

1. "Log first (bottom/nested) exception" (.NestedExceptionStack) option force EurekaLog to use original exceptions (nested root) for logging. This includes class, message, call stack, BugID and other exception-related properties to be stored in log file, shown in "detailed" dialogs and/or sent over network. This option doesn't affect any other visual appearance. If there is no nested exception - this option will have no effect, the behavior will be the same as if "Log last (top) exception" would be selected. This option is recommended option for typical application.

2. "Log last (top/chained) exception" (.NestedExceptionStack) option force EurekaLog to use chained exceptions for logging. This includes class, message, call stack, BugID and other exception-related properties to be stored in log file, shown in "detailed" dialogs and/or sent over network. This option doesn't affect any other visual appearance. Use this option for backward-compatible behavior.

3. "Show first (bottom/nested) exception" (.NestedExceptionMessage) option force EurekaLog to use original exceptions (nested root) for visual display. This includes error messages, dialogs and other visual interactions with user. This option doesn't affect logging. If there is no nested exception - this option will have no effect, the behavior will be the same as if "Show last (top) exception" would be selected.

4. "Show last (top/chained) exception" (.NestedExceptionMessage) option force EurekaLog to use chained exceptions for visual display. This includes error messages, dialogs and other visual interactions with user. This option doesn't affect logging. This is recommended option for most project types.

5. "Show all exceptions" (.NestedExceptionMessage) option force EurekaLog to show messages from all currently active exceptions (each message on new line). This includes error messages, dialogs and other visual interactions with user. This option doesn't affect logging. This is default behavior of Delphi and C++ Builder applications starting with Delphi 2009, but it's generally not recommended (unless you want extra-detailed error display).

6. "Custom" (.CustomExceptionMessage) option allows you to override any exception message with custom string. This option is used for error messages, dialogs and other visual interactions with user. This option doesn't affect logging. Specifying a message will override any exception message with the specified string. Use this option to hide implementation details from end-user. Message overriding can also be done by using exception filters or custom attributes.

7. "Use exception's custom message if available" (.UseExceptionComments) option allow you to override exception message with custom string individually for each exception. This option is used for error messages, dialogs and other visual interactions with user. This option doesn't affect logging. It can be combined with any of the previous options (items 3-6).

Each exception has associated .AdditionalInfo field. You can store any information in that field. It's like Tag field, except it has String type.

You can use this feature to override original message with custom message, but still preserve original information. This override is used only for visual display. Log files are unaffected.

This feature allows you to use per-exception override (see also "Override Exception Message" option). If you want to override all messages - just use "Custom" option above.

Note: some error dialogs like WER and system logging do not display error message to user (instead, they log exception details). Thus, such dialog are unaffected by the options above (items 3-7).

Secondary exceptions

Secondary exception is an exception which occurs during processing of another exception. For example:

procedure TForm1.Timer1Timer(Sender: TObject);
begin
  raise Exception.Create('Exception during message pumping');
end;

This code will raise (throw) an exception. EurekaLog will catch this exception and process it: create bug report and show a dialog. Showing dialog means processing window messages, which means that this code will raise a second (secondary) exception, which EurekaLog will catch and process it. In other words, secondary exceptions come from message handlers (timers, callbacks, events, etc.).

1. "Do nothing special" (.SecondaryExceptions) option will tell EurekaLog that it should act as RTL. In other words, no special actions will be taken. This means that any secondary exception will trigger EurekaLog (again) and will be processed as any other exception. Use this option if you want most details (e.g. reports about each and every exception).

Warning: make sure to set up auto-restart when using this option, because your application may enter endless cycle of showing secondary exceptions.

2. "Ignore like EAbort" (.SecondaryExceptions) option will tell EurekaLog to completely ignore all exceptions while displaying exception dialog.

Warning: this option will not prevent secondary exceptions from being thrown. Secondary exceptions will be raised, processed, but will be silently ignored (e.g. no bug report, no dialog, no sending).

This option is recommended, because it allows your application (main window) to remain responsive, while blocks exception dialogs from secondary exceptions.

3. "Block thread" (.SecondaryExceptions) option will tell EurekaLog to handle each exception in a service background thread. Running exception dialog in a background thread ensures that any secondary exceptions from exception's thread will not affect exception's dialog. Original exception's thread will be blocked until background thread finishes.

This is the only option that prevents secondary exception from being raised.

Warnings:

We do not recommend to use this option, unless you want to ensure that secondary exceptions do not occur.

Note: EurekaLog can still spawn background threads to handle some special exceptions even if this option is not selected. For example, stack overflow exception will always spawn a background thread, because exception's thread will have no stack space left.

See also: