Logging best practices

[rainij]

Do you have some best practices for logging?

It can happen all the time that for example a QDMI device encounters an error. Sometimes fatal ones. QDMI has a very low level interface were by default (if nobody implementes a more elaborate solution) you only see that e.g. a fatal error occured (enum QDMI_ERROR_FATAL). Even if no clear error message is reported to the user (whoever counts as the user) it would be good if at least the people running the device can quickly infer what went wrong. In deployed devices (release) this means e.g. the HPC center, during development the developer gets quick feedback.

An abstract example could be the following: Your device depends on some environment variable being set. E.g. THE_PASSWORD. It makes sense to report a fatal error to the user, but no details on the fact that we use this particular variable (for security reasons). On the other hand developers are quickly reminded that they have to set this variable (e.g. before testing). It is certainly also helpful for deployed instances.

I can of course always use std::cout and std::cerr. I would like to have some feedback on this. Any recommendations? Does it matter at all what each device prints? Is there something standardized in the making?

[rainij]

@burgholzer @ystade @echavarria-lrz any oppinions feedback on that 🙏 .

[echavarria-mqv]

Bringing @mnfarooqi to the mix

[burgholzer]

Logging can indeed be rather helpful during development.
The current solutions that we have employed mostly involve using a hand-rolled logging library or to make use of one of the existing C++ logging libraries out there, like spdlog.
The difference between production and development would typically just be the logging level.

There is no dedicated policy on what a device may or may not print to std::cout or std::cerr. So, at the moment, a device is free to make use of these streams extensively.

One thing that @ystade and I have been talking about briefly was to add a device-level property LASTERRORMSG that can be used to programmatically query (from the user side) as well as report (from the device side) the last error message.
A similar property could be added to the Job interface for querying individual jobs for their errors (or logs in general).

[mnfarooqi]

It would also be a good idea to add a new session parameter that allows you to set the level of verbosity (for example INFO, WARNING, ERROR or NONE) for console output (std::cout or std::cerr) if such output is provided.

[rainij]

One thing concerning the LASTERRORMSG. Some people like me who only implement the device interface might not have a good feeling what makes sense on the user side. It could happen that such a features ends up unimplemented due to missing support from the device side (as it seems not "essential" to make things work). Maybe a good documentation solves the issue, or it is not an issue at all, who knows.

[burgholzer]

Thanks for raising this concern. An entirely valid point.
Maybe a general documentation section on logging combined with @mnfarooqi’s proposal above to set the log level could be the better way forward.

[rainij]

Thanks for you feedback. OK then in the short term I will just log whatever I think is useful. In the long run I know that something is under discussion.

[rainij]

Should I leave the discussion open for possible future conversations or should I just mark it as answered?

[burgholzer]

You can mark the reply above as an answer. We can always reopen the discussion or open a new one.