com.google.common.flogger

Interface GoogleLoggingApi<API extends GoogleLoggingApi<API>>

Type Parameters:

API - The api returned during method chaining (possibly an extension of this interface).

All Superinterfaces:

com.google.common.flogger.LoggingApi<API>

All Known Subinterfaces:

GoogleLogger.Api

All Known Implementing Classes:

GoogleLogContext, GoogleLoggingApi.NoOp

@CheckReturnValue
public interface GoogleLoggingApi<API extends GoogleLoggingApi<API>>
extends com.google.common.flogger.LoggingApi<API>

Google specific extensions to the fluent logging API.

If a team wishes to implement its own logging extensions, it must extend this API (in the same way that this API was extended from LoggingApi) and extend GoogleLogContext similarly. This should all be tied together by implementing an alternate implementation of GoogleLogger.

However, if you wish to extend the default logging API, please contact flogger-dev@ first.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	GoogleLoggingApi.NoOp<API extends GoogleLoggingApi<API>> An implementation of GoogleLoggingApi which does nothing and discards all parameters.

Method Summary

Modifier and Type	Method and Description
<T> API	with(com.google.common.flogger.MetadataKey<T> key, T value) Associates a metadata key constant with a runtime value for this log statement in a structured way that is accessible to logger backends.

Methods inherited from interface com.google.common.flogger.LoggingApi

atMostEvery, every, isEnabled, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, log, logVarargs, withCause, withInjectedLogSite, withInjectedLogSite, withStackTrace

Method Detail

with

<T> API with(com.google.common.flogger.MetadataKey<T> key,
             @Nullable
             T value)

Associates a metadata key constant with a runtime value for this log statement in a structured way that is accessible to logger backends.

This method is not a replacement for general parameter passing in the LoggingApi.log() method and should be reserved for keys/values with specific semantics. Examples include:

• Keys that are recognised by specific logger backends (typically to control logging behaviour in some way).
• Key value pairs which are explicitly extracted from logs by tools.

Metadata keys can support repeated values (see MetadataKey.canRepeat()), and if a repeatable key is used multiple times in the same log statement, the effect is to collect all the given values in order. If a non-repeatable key is passed multiple times, only the last value is retained (though callers should not rely on this behavior and should simply avoid repeating non-repeatable keys).

If value is null, this method is a no-op. This is useful for specifying conditional values (e.g. via logger.atInfo().with(MY_KEY, getValueOrNull()).log(...)).

Parameters:

key - the metadata key (expected to be a static constant)

value - a value to be associated with the key in this log statement. Null values are allowed, but the effect is always a no-op

Throws:

java.lang.NullPointerException - if the given key is null

See Also:

MetadataKey