[Proposal] Java logging best practices additions

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

[Proposal] Java logging best practices additions

vmassol
Administrator
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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Marius Dumitru Florea
On Sat, Feb 15, 2014 at 7:13 PM, [hidden email] <[hidden email]> wrote:

> 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?

+1, I'll update my code :)

Thanks,
Marius

>
> Thanks
> -Vincent
>
>
>
>
>
>
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Thomas Mortagne
Administrator
In reply to this post by vmassol
+1

On Sat, Feb 15, 2014 at 6:13 PM, [hidden email] <[hidden email]> wrote:

> 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs



--
Thomas Mortagne
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Denis Gervalle-2
+1


On Sun, Feb 16, 2014 at 2:47 PM, Thomas Mortagne
<[hidden email]>wrote:

> +1
>
> On Sat, Feb 15, 2014 at 6:13 PM, [hidden email] <[hidden email]>
> wrote:
> > Hi devs,
> >
> > On
> http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPracticeswe 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
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/devs
>
>
>
> --
> Thomas Mortagne
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>



--
Denis Gervalle
SOFTEC sa - CEO
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Eduard Moraru
+1

Thanks,
Eduard


On Sun, Feb 16, 2014 at 6:27 PM, Denis Gervalle <[hidden email]> wrote:

> +1
>
>
> On Sun, Feb 16, 2014 at 2:47 PM, Thomas Mortagne
> <[hidden email]>wrote:
>
> > +1
> >
> > On Sat, Feb 15, 2014 at 6:13 PM, [hidden email] <[hidden email]>
> > wrote:
> > > Hi devs,
> > >
> > > On
> >
> http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPracticeswehave 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
> > > [hidden email]
> > > http://lists.xwiki.org/mailman/listinfo/devs
> >
> >
> >
> > --
> > Thomas Mortagne
> > _______________________________________________
> > devs mailing list
> > [hidden email]
> > http://lists.xwiki.org/mailman/listinfo/devs
> >
>
>
>
> --
> Denis Gervalle
> SOFTEC sa - CEO
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
>
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

vmassol
Administrator
In reply to this post by vmassol
I’ve updated http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPractices

Thanks
-Vincent 

On 15 Feb 2014 at 18:13:36, [hidden email] ([hidden email](mailto:[hidden email])) wrote:

> 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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Roman Muntyanu
Hi Vincent,

  Just of curiosity, XWiki uses 2 approaches for declaring logger: 1) via dependency injection 2) as a static member via slf4j's factory method
  However slf4j explicitly recommends using factory method [1]

  What's the rationale behind approach 1)? (couldn’t find it explicitly stated in mailing thread [2] )

Roman
   [1]  http://www.slf4j.org/faq.html#declared_static 
   [2]  http://xwiki.475771.n2.nabble.com/Proposal-Switch-to-injecting-Loggers-td6348177.html 

-----Original Message-----
From: devs [mailto:[hidden email]] On Behalf Of [hidden email]
Sent: Tuesday, February 18, 2014 19:39 PM
To: XWiki Developers
Subject: Re: [xwiki-devs] [Proposal] Java logging best practices additions

I’ve updated http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPractices

Thanks
-Vincent 

On 15 Feb 2014 at 18:13:36, [hidden email] ([hidden email](mailto:[hidden email])) wrote:

> 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
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

vmassol
Administrator
Hi Roman,

On 19 Feb 2014 at 10:16:24, Roman Muntyanu ([hidden email](mailto:[hidden email])) wrote:

> Hi Vincent,
>  
> Just of curiosity, XWiki uses 2 approaches for declaring logger: 1) via dependency injection 2) as a static member via slf4j's factory method
> However slf4j explicitly recommends using factory method [1]

Both are actually using the SLF4J factory method.

In case of 1) the Component Manager does this:

    protected Object createLogger(Class< ? > instanceClass)
    {
        return LoggerFactory.getLogger(instanceClass);
    }

As you can see it’s the same.

The reason for 1) are mentioned in the mail you reference (http://xwiki.475771.n2.nabble.com/Proposal-Switch-to-injecting-Loggers-td6348177.html), namely:

"
Rationale: 
* More consistent with how we inject dependencies 
* Makes it easier to move to another DI framework later on (CDI, Guice, etc) since the way to implement this with them is to use the JSR299 @Producer annotation on a class that produces Loggers. 
* Allows to keep the current logging behavior unchanged for backward compatibility (we juste deprecate it). 


Thanks
-Vincent

> What's the rationale behind approach 1)? (couldn’t find it explicitly stated in mailing thread [2] )
>  
> Roman
> [1] http://www.slf4j.org/faq.html#declared_static
> [2] http://xwiki.475771.n2.nabble.com/Proposal-Switch-to-injecting-Loggers-td6348177.html
>  
> -----Original Message-----
> From: devs [mailto:[hidden email]] On Behalf Of [hidden email]
> Sent: Tuesday, February 18, 2014 19:39 PM
> To: XWiki Developers
> Subject: Re: [xwiki-devs] [Proposal] Java logging best practices additions
>  
> I’ve updated http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBestPractices
>  
> Thanks
> -Vincent  
>  
> On 15 Feb 2014 at 18:13:36, [hidden email] ([hidden email](mailto:[hidden email])) wrote:
>  
> > 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs
Reply | Threaded
Open this post in threaded view
|

Re: [Proposal] Java logging best practices additions

Roman Muntyanu
Sorry for terminology confusion.

From what I've understood, slf4j actually recommends
    private static Logger logger;
over
    private Logger logger;

So it's slightly more about how the logger is stored than how it's obtained

-----Original Message-----
From: Vincent Massol [mailto:[hidden email]] On Behalf Of [hidden email]
Sent: Wednesday, February 19, 2014 14:56 PM
To: XWiki Developers
Cc: Roman Muntyanu
Subject: Re: [xwiki-devs] [Proposal] Java logging best practices additions

Hi Roman,

On 19 Feb 2014 at 10:16:24, Roman Muntyanu ([hidden email](mailto:[hidden email])) wrote:

> Hi Vincent,
>  
> Just of curiosity, XWiki uses 2 approaches for declaring logger: 1)
> via dependency injection 2) as a static member via slf4j's factory
> method However slf4j explicitly recommends using factory method [1]

Both are actually using the SLF4J factory method.

In case of 1) the Component Manager does this:

    protected Object createLogger(Class< ? > instanceClass)
    {
        return LoggerFactory.getLogger(instanceClass);
    }

As you can see it’s the same.

The reason for 1) are mentioned in the mail you reference (http://xwiki.475771.n2.nabble.com/Proposal-Switch-to-injecting-Loggers-td6348177.html), namely:

"
Rationale:
* More consistent with how we inject dependencies
* Makes it easier to move to another DI framework later on (CDI, Guice, etc) since the way to implement this with them is to use the JSR299 @Producer annotation on a class that produces Loggers.
* Allows to keep the current logging behavior unchanged for backward compatibility (we juste deprecate it). “

Thanks
-Vincent

> What's the rationale behind approach 1)? (couldn’t find it explicitly
> stated in mailing thread [2] )
>  
> Roman
> [1] http://www.slf4j.org/faq.html#declared_static
> [2]
> http://xwiki.475771.n2.nabble.com/Proposal-Switch-to-injecting-Loggers
> -td6348177.html
>  
> -----Original Message-----
> From: devs [mailto:[hidden email]] On Behalf Of
> [hidden email]
> Sent: Tuesday, February 18, 2014 19:39 PM
> To: XWiki Developers
> Subject: Re: [xwiki-devs] [Proposal] Java logging best practices
> additions
>  
> I’ve updated
> http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HLoggingBe
> stPractices
>  
> Thanks
> -Vincent
>  
> On 15 Feb 2014 at 18:13:36, [hidden email] ([hidden email](mailto:[hidden email])) wrote:
>  
> > 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
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs
> _______________________________________________
> devs mailing list
> [hidden email]
> http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________
devs mailing list
[hidden email]
http://lists.xwiki.org/mailman/listinfo/devs