Package com.jcabi.aspects

Annotation Type Loggable

  • @Documented
@Retention(RUNTIME)
@Target({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
    See Also:
    Logger, http://aspects.jcabi.com/, Java Method Logging with AOP and Annotations, by Yegor Bugayenko

    • Field Summary

      Fields 
      Modifier and Type Fields Description
      static int DEBUG
      DEBUG level of logging.
      static int ERROR
      ERROR level of logging.
      static int INFO
      INFO level of logging.
      static int TRACE
      TRACE level of logging.
      static int WARN
      WARN level of logging.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element 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.

    • Field Detail

      • TRACE

        static final int TRACE
        TRACE level of logging.

      • DEBUG

        static final int DEBUG
        DEBUG level of logging.

      • INFO

        static final int INFO
        INFO level of logging.

      • WARN

        static final int WARN
        WARN level of logging.

      • ERROR

        static final int ERROR
        ERROR level of logging.

    • Element Detail

      • value

        int value
        Level of logging.
        Returns:
        The log level
        Default:
        2

      • limit

        int limit
        Maximum amount allowed for this method (a warning will be issued if it takes longer).
        Returns:
        The limit
        Since:
        0.7.6
        Default:
        1

      • unit

        TimeUnit unit
        Time unit for the limit.
        Returns:
        The time unit
        Since:
        0.7.14
        Default:
        java.util.concurrent.TimeUnit.MINUTES

      • trim

        boolean trim
        Shall we trim long texts in order to make log lines more readable?
        Returns:
        The flag
        Since:
        0.7.13
        Default:
        true

      • prepend

        boolean prepend
        Method entry moment should be reported as well (by default only an exit moment is reported).
        Returns:
        The flag
        Since:
        0.7.16
        Default:
        false

      • ignore

        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.

        Returns:
        Array of types
        Since:
        0.7.17
        Default:
        {}

      • skipResult

        boolean skipResult
        Skip logging of result, replacing it with dots?
        Returns:
        The flag
        Since:
        0.7.19
        Default:
        false

      • skipArgs

        boolean skipArgs
        Skip logging of arguments, replacing them all with dots?
        Returns:
        The flag
        Since:
        0.7.19
        Default:
        false

      • logThis

        boolean logThis
        Add toString() result to log line.
        Returns:
        The flag
        Since:
        0.8.1
        Default:
        false

      • precision

        int precision
        The precision (number of fractional digits) to be used when displaying the measured execution time.
        Returns:
        The precision
        Since:
        0.18
        Default:
        2

      • name

        String name
        The name of the logger to be used. If not specified, defaults to the class name of the annotated class or method.
        Returns:
        The logger's name
        Since:
        0.18
        Default:
        ""