withInjectedLogSite

Sets the log site for the current log statement. Explicit log site injection is very rarely necessary, since either the log site is injected automatically, or it is determined at runtime via stack analysis. The one use case where calling this method explicitly may be useful is when making logging helper methods, where some common project specific logging behavior is enshrined. For example, you can write:

public void logStandardWarningAt(LogSite logSite, String message, Object... args) {
  logger.atWarning()
      .withInjectedLogSite(logSite)
      .atMostEvery(5, MINUTES)
      .logVarargs(message, args);
}

import static com.google.common.flogger.LogSites.logSite;

logStandardWarningAt(logSite(), "Badness");
...
logStandardWarningAt(logSite(), "More badness: %s", getData());

Now each of the call sites for the helper method is treated as if it were in the logging API, and things like rate limiting work separately for each, and the location in the log statement will be the point at which the helper method was called.

It is very important to note that the logSite() call can be very slow, since determining the log site can involve stack trace analysis. It is only recommended in cases where logging is expected to occur (e.g. WARNING level or above). Luckily, there is typically no need to implement helper methods for FINE logging, since it's usually less structured and doesn't normally need to follow any specific "best practice" behavior.

Note however that any stack traces generated by withStackTrace will still contain the complete stack, including the call to the logger itself inside the helper method.

This method must only be explicitly called once for any log statement, and if this method is called multiple times the first invocation will take precedence. This is because log site injection (if present) is expected to occur just before the final log() call and must be overrideable by earlier (explicit) calls. A null argument has no effect.

Parameters

Internal method not for public use. This method is only intended for use by the logger agent and related classes and should never be invoked manually.

Parameters