Now daos is a much larger established codebase it’s become apparent that the origional logging macros are insufficient, and inconsistently used across the code, leading to poor user experience and difficulty in reporting or diagnosing issues.
The most commonly used debug levels are:
ERROR- This is an unexpected error, something that should not happen as it's either unexpected or a API violation.WARNING- This is used much less and typically in cases where the code can take an alternative path and continue.INFO- This is used for startup messages, configuration options applied etc. This will typically be quiet after the process has started but there are exceptions.DEBUG- These are off by default, can be verbose and log progress through iterations. Various areas of the code are differently 'chatty' or verbose. DEBUG level logs are really intended for developers so are not covered by these new macros, they do not typically use the DF_RC macro and do not need to - it adds extra text to the source which is distracting when working on debugging or development.
The coding standards have always said that error logs should include the value of rc, and that it should be at the end of the line however this has been inconsistency applied. The addition of DF_RC to include errors strings as well as numbers was welcome but didn’t address the inconsistency issue, and means that the error messages take up more space in the source for largely boiler-plate text, in addition only some areas of the codebase have adopted them.
Some effort has been made to check for consistency in error output and looking for a standard format, however the depends on having tests that provoke error paths which is time consuming (although productive) and the fixes have involved adding boiler-plate text to the source - improving the quality of error reports for users, but making the code itself larger and harder to read.
The new error macros resolve this issue by taking the rc value as an option to the macro itself, this allows the boiler-plate text to go in the macro and the have it apply the formatting - other printf formatting can still be used. No whitespace, formatting or newlines should be included at the end of the new macros, this will be added automatically.
Preferred:
DL_ERROR(rc, "failed to create handle hash table"); DL_ERROR(rc, "Failed to replay %s", act_opc2str(act->ac_opc));
Old macros:
D_ERROR("failed to create handle hash table: "DF_RC"\n",
DP_RC(rc));
D_ERROR("Failed to replay %s, "DF_RC"\n", act_opc2str(act->ac_opc), DP_RC(rc));