com.jcabi.aspects

Annotation Type Loggable

@Documented
@Retention(value=RUNTIME)
@Target(value={METHOD,TYPE})
public @interface Loggable

Makes a method loggable via Logger.

For example, this load() method produces a log line on every call:

 @Loggable
 String load(String resource) throws IOException {
   return "something";
 }

You can configure the level of logging:

 @Loggable(Loggable.DEBUG)
 void save(String resource) throws IOException {
   // do something
 }

Since version 0.7.6, you can specify a maximum execution time limit for a method. If such a limit is reached a logging message will be issued with a WARN priority. It is a very convenient mechanism for profiling applications in production. Default value of a limit is 1 second.

 @Loggable(limit = 2)
 void save(String resource) throws IOException {
   // do something, potentially slow
 }

Since version 0.7.14 you can change the time unit for the "limit" parameter. Default unit of measurement is a second:

 @Loggable(limit = 200, unit = TimeUnit.MILLISECONDS)
 void save(String resource) throws IOException {
   // do something, potentially slow
 }

Since version 0.7.17 you can ignore certain exception types, and they won't be logged when thrown. It is very useful when exceptions are used to control flow (which is not a good practice, but is still used in some frameworks, for example in JAX-RS):

 @Loggable(ignore = WebApplicationException.class)
 String get() {
   if (not_logged_in()) {
     throw new WebApplicationException(forward_to_login_page());
   }
 }

Since version 0.8 you can mark some exceptions as "always to be ignored", using Loggable.Quiet annotation.

Since:

0.7.2

Version:

$Id$

Author:

Yegor Bugayenko (yegor@tpc2.com)

See Also:

Logger, http://aspects.jcabi.com/, Java Method Logging with AOP and Annotations, by Yegor Bugayenko

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
Class<? extends Throwable>[]	ignore List of exception types, which should not be logged if thrown.
int	limit Maximum amount allowed for this method (a warning will be issued if it takes longer).
boolean	logThis Add toString() result to log line.
String	name The name of the logger to be used.
int	precision The precision (number of fractional digits) to be used when displaying the measured execution time.
boolean	prepend Method entry moment should be reported as well (by default only an exit moment is reported).
boolean	skipArgs Skip logging of arguments, replacing them all with dots?
boolean	skipResult Skip logging of result, replacing it with dots?
boolean	trim Shall we trim long texts in order to make log lines more readable?
TimeUnit	unit Time unit for the limit.
int	value Level of logging.

Element Detail

value

public abstract int value

Level of logging.

Default:

2

limit

public abstract int limit

Maximum amount allowed for this method (a warning will be issued if it takes longer).

Since:

0.7.6

Default:

1

unit

public abstract TimeUnit unit

Time unit for the limit.

Since:

0.7.14

Default:

java.util.concurrent.TimeUnit.MINUTES

trim

public abstract boolean trim

Shall we trim long texts in order to make log lines more readable?

Since:

0.7.13

Default:

true

prepend

public abstract boolean prepend

Method entry moment should be reported as well (by default only an exit moment is reported).

Since:

0.7.16

Default:

false

ignore

public abstract Class<? extends Throwable>[] ignore

List of exception types, which should not be logged if thrown.

You can also mark some exception types as "always to be ignored", using Loggable.Quiet annotation.

Since:

0.7.17

Default:

{}

skipResult

public abstract boolean skipResult

Skip logging of result, replacing it with dots?

Since:

0.7.19

Default:

false

skipArgs

public abstract boolean skipArgs

Skip logging of arguments, replacing them all with dots?

Since:

0.7.19

Default:

false

logThis

public abstract boolean logThis

Add toString() result to log line.

Since:

0.8.1

Default:

false

precision

public abstract int precision

The precision (number of fractional digits) to be used when displaying the measured execution time.

Since:

0.18

To do:

#86 Let's document the usage of this parameter, including its effects and default setting, in the annotation-loggable.apt.vm page.

Default:

2

name

public abstract String name

The name of the logger to be used. If not specified, defaults to the class name of the annotated class or method.

Since:

0.18

To do:

#85 Let's document the usage of this parameter in the annotation-loggable.apt.vm site page.

Default:

""