DPU Exceptions - Error Reporting

This section contains a short guide on some ways to inform users about DPU exceptions.

There are two ways how to communicate such information to a user:

  • Logs

  • Events (messages)

Events are meant to be used to deliver more important information than logs. There is no strict rule when to use event and when to use logs. The idea is that if everything goes well then from events a user should get all the information he needs about DPU execution such as: which mode was used, optionally, which resources have been processed, etc.

Note

You should handle event messages regarding resources with care, as there might be a huge number of resources.

Logs on the other hand should provide detailed information about the DPU's execution, which is useful mainly when the DPU is being debugged.

Fatal DPU Failure

If you want to denote fatal DPU failure, the DPU should throw DPUException.

Wherever possible, use this exception to report DPU failure.

Note

You can use ContextUtils to generate this exception and apply localisation to the given message.

In certain situations it may not be easy to throw DPUException, for example in case of multi-threaded DPUs.

In that case, ERROR event can be emitted: ERROR event has the same effect as DPUException: the DPU is considered to fail and pipeline execution is stopped.

Summary on Error Reporting

The following recommended ways of sending information to users exist:

  • Use Events to report important events to the user.

  • Use Logs to log anything else.

  • Use DPUException to report DPU failure.

Note

Some helpers also throw DPUException in case of fatal failure. In such cases the exception should not be catched and the DPU execution should fail.

Error event causes the DPU to end with 'Error'. A Warning event, error log and a Warning log message cause the DPU to end with Warning.