handle
Handles an error in a log statement. Errors passed into this method are expected to have only three distinct causes:
- Bad format strings in log messages (e.g.
"foo=%Q". These will always be instances of ParseException and contain human readable error messages describing the problem. - A backend optionally choosing not to handle errors from user code during formatting. This is not recommended (see below) but may be useful in testing or debugging.
- Runtime errors in the backend itself.
It is recommended that backend implementations avoid propagating exceptions in user code (e.g. calls to toString()), as the nature of logging means that log statements are often only enabled when debugging. If errors were propagated up into user code, enabling logging to look for the cause of one issue could trigger previously unknown bugs, which could then seriously hinder debugging the original issue.
Typically a backend would handle an error by logging an alternative representation of the "bad" log data, being careful not to allow any more exceptions to occur. If a backend chooses to propagate an error (e.g. when testing or debugging) it must wrap it in to avoid it being re-caught.
Parameters
the exception throw when badData was initially logged.
the original LogData instance which caused an error. It is not expected that simply trying to log this again will succeed and error handlers must be careful in how they handle this instance, its arguments and metadata. References to badData must not be held after the handleError invocation returns.
Throws
to indicate an error which should be propagated into user code.