Hi devs,
On
http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPractices
we have some best practices defined for logging.
I’d like to propose some additions.
Best practices:
* Use SLF4J
* If you’re in a component get the logger injected using @Inject private Logger
logger otherwise use:
private static final Logger LOGGER = LoggerFactory.getLogger(My.class);
* Use logger.info() when it’s absolutely necessary for the user to see the
message in the logs. Usually only used at startup and we want to limit what the
user sees to the absolute necessary to avoid swamping him.
* Use logger.warning() when an error happens but it doesn’t compromise the
stability and general working of an XWiki instance. A warning just shows the
user that something has gone wrong and it should provide him with as much
information as possible to solve the issue. Do not print a stack trace when you
output a warning since stack traces fill the logs and should be reserved for
errors. In the view of users stack traces are synonymous with errors. We want
it to be easy for admins to visually check the log files and see important
problems (ie errors).
* Use logger.error() when there’s an important problem that compromises the
stability of the XWiki instance or that prevent an important system from
working and that should not have happened. Always pass a stack trace when
logging errors since it’s something that shouldn’t have happened an a developer
will need to debug the problem to fix it.
* Always log as much information as possible to make it easier to understand
what’s going on.
* Surround parameters with “[]” in order to separate visually the text from the
parameters and also clearly notice when leading/trailing spaces are located in
parameters.
* For improved performances, always use the vararg signature of SLF4J for
logging parameters and do not concatenate them manually:
this.logger.debug("Test message with [{}] and [{}]", param1, param2);
vs
this.logger.debug("Test message with [“ + param1 + "] and [“ + param2 + “]",
param1, param2);
* When logging a warning, we don’t want to log the full stack trace but it’s
still interesting from time to time to display the root issue. If you do the
following you won’t get the root issue:
LOGGER.warn("Failed to determine if the index exists: [{}]. Trying to recreate
the index..”, e.getMessage());
Instead use ExceptionUtils from commons lang:
LOGGER.warn("Failed to determine if the index exists: [{}]. Trying to recreate
the index..”, ExceptionUtils.getRootCauseMessage(e));
WDYT?
Thanks
-Vincent
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
