Package com.google.common.flogger

Class LogSites

  • public final class LogSites
extends Object
    Helper class to generate log sites for the current line of code. This class is deliberately isolated (rather than having the method in LogSite itself) because manual log site injection is rare and by isolating it into a separate class may help encourage users to think carefully about the issue.

    • Method Detail

      • callerOf

        public static LogSite callerOf​(Class<?> loggingApi)
        Returns a LogSite for the caller of the specified class. This can be used in conjunction with the LoggingApi.withInjectedLogSite(LogSite) method to implement logging helper methods. In some platforms, log site determination may be unsupported, and in those cases this method will always return the LogSite.INVALID instance.

        For example (in MyLoggingHelper): 

        
 public static void logAndSomethingElse(String message, Object... args) {
   logger.atInfo()
       .withInjectedLogSite(callerOf(MyLoggingHelper.class))
       .logVarargs(message, args);
 }

        This method should be used for the simple cases where the class in which the logging occurs is a public logging API. If the log statement is in a different class (not the public logging API) and the LogSite instance needs to be passed through several layers, consider using logSite() instead to avoid too much "magic" in your code.

        You should also seek to ensure that any API used with this method "looks like a logging API". It's no good if a log entry contains a class and method name which doesn't correspond to anything the user can relate to. In particular, the API should probably always accept the log message or at least some of its parameters, and should always have methods with "log" in their names to make the connection clear.

        It is very important to note that this method can be very slow, since determining the log site can involve stack trace analysis. It is only recommended that it is used for cases where logging is expected to occur (e.g. INFO level or above). Implementing a helper method for FINE logging is usually unnecessary (it doesn't normally need to follow any specific "best practice" behavior).

        Note that even when log site determination is supported, it is not defined as to whether two invocations of this method on the same line of code will produce the same instance, equivalent instances or distinct instance. Thus you should never invoke this method twice in a single statement (and you should never need to).

        Note that this method call may be replaced in compiled applications via bytecode manipulation or other mechanisms to improve performance.

        Parameters:
        loggingApi - the logging API to be identified as the source of log statements (this must appear somewhere on the stack above the point at which this method is called).
        Returns:
        the log site of the caller of the specified logging API, or LogSite.INVALID if the logging API was not found.

      • logSite

        public static LogSite logSite()
        Returns a LogSite for the current line of code. This can be used in conjunction with the LoggingApi.withInjectedLogSite(LogSite) method to implement logging helper methods. In some platforms, log site determination may be unsupported, and in those cases this method will always return the LogSite.INVALID instance.

        For example (in MyLoggingHelper): 

        
 public static void logAndSomethingElse(LogSite logSite, String message, Object... args) {
   logger.atInfo()
       .withInjectedLogSite(logSite)
       .logVarargs(message, args);
 }
        where callers would do: 
        
 MyLoggingHelper.logAndSomethingElse(logSite(), "message...");

        Because this method adds an additional parameter and exposes a Flogger specific type to the calling code, you should consider using callerOf(Class) for simple logging utilities.

        It is very important to note that this method can be very slow, since determining the log site can involve stack trace analysis. It is only recommended that it is used for cases where logging is expected to occur (e.g. INFO level or above). Implementing a helper method for FINE logging is usually unnecessary (it doesn't normally need to follow any specific "best practice" behavior).

        Note that even when log site determination is supported, it is not defined as to whether two invocations of this method on the same line of code will produce the same instance, equivalent instances or distinct instance. Thus you should never invoke this method twice in a single statement (and you should never need to).

        Note that this method call may be replaced in compiled applications via bytecode manipulation or other mechanisms to improve performance.

        Returns:
        the log site of the caller of this method.