com.google.common.flogger.backend.system

Class LoggingContext

java.lang.Object

com.google.common.flogger.backend.system.LoggingContext

Direct Known Subclasses:

EmptyLoggingContext

public abstract class LoggingContext
extends java.lang.Object

An API for injecting scoped metadata for log statements (either globally or on a per-request basis). This is implemented as an abstract class (rather than an interface) to reduce to risk of breaking existing implementations if the API changes.

Essential Implementation Restrictions

Any implementation of this API MUST follow the rules listed below to avoid any risk of re-entrant code calling during logger initialization. Failure to do so risks creating complex, hard to debug, issues with Flogger configuration.

1. Implementations MUST NOT attempt any logging in static methods or constructors.
2. Implementations MUST NOT statically depend on any unknown code.
3. Implementations MUST NOT depend on any unknown code in constructors.

Note that logging and calling arbitrary unknown code (which might log) are permitted inside the instance methods of this API, since they are not called during platform initialization. The easiest way to achieve this is to simply avoid having any non-trivial static fields or any instance fields at all in the implementation.

While this sounds onerous it's not difficult to achieve because this API is a singleton, and can delay any actual work until its methods are called. For example if any additional state is required in the implementation, it can be held via a "lazy holder" to defer initialization.

Constructor Summary

Constructors

Constructor and Description
LoggingContext()

Method Summary

Modifier and Type	Method and Description
abstract com.google.common.flogger.backend.Tags	getTags() Returns a set of tags to be added to a log statement.
abstract boolean	shouldForceLogging(java.lang.String loggerName, java.util.logging.Level level, boolean isEnabledByLevel) Returns whether the given logger should have logging forced at the specified level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LoggingContext

public LoggingContext()

Method Detail

shouldForceLogging

public abstract boolean shouldForceLogging(java.lang.String loggerName,
                                           java.util.logging.Level level,
                                           boolean isEnabledByLevel)

Returns whether the given logger should have logging forced at the specified level. When logging is forced for a log statement it will be emitted regardless or the normal log level configuration of the logger and ignoring any rate limiting or other filtering.

A default implementation of this method should simply return false.

loggerName can be used to look up specific configuration, such as log level, for the logger, to decide if a log statement should be forced. This information might vary depending on the context in which this call is made, so the result should not be cached.

isEnabledByLevel indicates that the log statement is enabled according to its log level, but a true value does not necessarily indicate that logging will occur, due to rate limiting or other conditional logging mechanisms. To bypass conditional logging and ensure that an enabled log statement will be emitted, this method should return true if isEnabledByLevel was true.

WARNING: This method MUST complete quickly and without allocating any memory. It is invoked for every log statement regardless of logging configuration, so any implementation must go to every possible length to be efficient.

Parameters:

loggerName - the fully qualified logger name (e.g. "com.example.SomeClass")

level - the level of the log statement being invoked

isEnabledByLevel - whether the logger is enabled at the given level

getTags

public abstract com.google.common.flogger.backend.Tags getTags()

Returns a set of tags to be added to a log statement. These tags can be used to provide additional contextual metadata to log statements (e.g. request IDs).

A default implementation of this method should simply return Tags.empty().