flogger-api/io.spine.logging.flogger/LogContext

LogContext

public abstract class LogContext<LOGGER extends AbstractLogger<API>, API extends FloggerApi<API>> implements FloggerApi<API>, LogData

The base context for a logging statement, which implements the base logging API.

This class is an implementation of the base FloggerApi interface and acts as a holder for any state applied to the log statement during the fluent call sequence. The lifecycle of a logging context is very short; it is created by a logger, usually in response to a call to the at method, and normally lasts only as long as the log statement.

This class should not be visible to normal users of the logging API and it is only needed when extending the API to add more functionality. In order to extend the logging API and add methods to the fluent call chain, the LoggingApi interface should be extended to add any new methods, and this class should be extended to implement them. A new logger class will then be needed to return the extended context.

Logging contexts are not thread safe.

Constructors

LogContext

protected void LogContext(Level level, boolean isForced)

Creates a logging context with the specified level, and with a timestamp obtained from the configured logging Platform.

protected void LogContext(Level level, boolean isForced, long timestampNanos)

Creates a logging context with the specified level and timestamp.

Types

Key

public final class Key

The predefined metadata keys used by the default logging API.

Properties

level

public final Level level

The log level of the log statement that this context was created for.

logSite

public FloggerLogSite logSite

The log site information for this log statement (set immediately prior to post-processing).

templateContext

public TemplateContext templateContext

The template context if formatting is required (set only after post-processing).

timestampNanos

public final long timestampNanos

The timestamp of the log statement that this context is associated with.

Functions

addMetadata

protected final void addMetadata<T>(FloggerMetadataKey<T> key, T value)

Adds the given key/value pair to this logging context.

api

protected abstract API api()

Returns the current API (which is just the concrete sub-type of this instance).

atMostEvery

public final API atMostEvery(int n, TimeUnit unit)

Modifies the current log statement to be emitted at most once per specified time period.

every

public final API every(int n)

Modifies the current log statement to be emitted at most one-in-N times.

getArguments

public final Array<Object> getArguments()

Returns the arguments to be formatted with the message.

getLevel

public final Level getLevel()

Returns the log level for the current log statement.

getLiteralArgument

public final Object getLiteralArgument()

Returns the single argument to be logged directly when no arguments were provided.

getLogger

protected abstract LOGGER getLogger()

Returns the logger which created this context.

getLoggerName

public final String getLoggerName()

Returns the logger name (which is usually a canonicalized class name) or null if not given.

getLogSite

public final FloggerLogSite getLogSite()

Returns the log site data for the current log statement.

getMessageParser

protected abstract MessageParser getMessageParser()

Returns the message parser used for all log statements made through this logger.

getMetadata

public final Metadata getMetadata()

Returns any additional metadata for this log statement.

getTemplateContext

public final TemplateContext getTemplateContext()

Returns a template key for this log statement, or null if the statement does not require formatting (in which case the message to be logged can be determined by calling getLiteralArgument).

getTimestampMicros

@Deprecated()

public final long ~~getTimestampMicros~~()

getTimestampNanos

public final long getTimestampNanos()

Returns a nanosecond timestamp for the current log statement.

isEnabled

public final boolean isEnabled()

Returns true if logging is enabled at the level implied for this API, according to the current logger backend.

log

public final void log()

Terminal log statement when a message is not required.

public final void log(String msg)

Logs the given literal string without interpreting any argument placeholders.

public final void log(String message, byte p1)

public final void log(String message, char p1)

public final void log(String message, int p1)

public final void log(String message, long p1)

public final void log(String message, short p1)

public final void log(String message, boolean p1, boolean p2)

public final void log(String message, boolean p1, byte p2)

public final void log(String message, boolean p1, char p2)

public final void log(String message, boolean p1, double p2)

public final void log(String message, boolean p1, float p2)

public final void log(String message, boolean p1, int p2)

public final void log(String message, boolean p1, @Nullable() Object p2)

public final void log(String message, boolean p1, long p2)

public final void log(String message, boolean p1, short p2)

public final void log(String message, byte p1, boolean p2)

public final void log(String message, byte p1, byte p2)

public final void log(String message, byte p1, char p2)

public final void log(String message, byte p1, double p2)

public final void log(String message, byte p1, float p2)

public final void log(String message, byte p1, int p2)

public final void log(String message, byte p1, @Nullable() Object p2)

public final void log(String message, byte p1, long p2)

public final void log(String message, byte p1, short p2)

public final void log(String message, char p1, boolean p2)

public final void log(String message, char p1, byte p2)

public final void log(String message, char p1, char p2)

public final void log(String message, char p1, double p2)

public final void log(String message, char p1, float p2)

public final void log(String message, char p1, int p2)

public final void log(String message, char p1, @Nullable() Object p2)

public final void log(String message, char p1, long p2)

public final void log(String message, char p1, short p2)

public final void log(String message, double p1, boolean p2)

public final void log(String message, double p1, byte p2)

public final void log(String message, double p1, char p2)

public final void log(String message, double p1, double p2)

public final void log(String message, double p1, float p2)

public final void log(String message, double p1, int p2)

public final void log(String message, double p1, @Nullable() Object p2)

public final void log(String message, double p1, long p2)

public final void log(String message, double p1, short p2)

public final void log(String message, float p1, boolean p2)

public final void log(String message, float p1, byte p2)

public final void log(String message, float p1, char p2)

public final void log(String message, float p1, double p2)

public final void log(String message, float p1, float p2)

public final void log(String message, float p1, int p2)

public final void log(String message, float p1, @Nullable() Object p2)

public final void log(String message, float p1, long p2)

public final void log(String message, float p1, short p2)

public final void log(String message, int p1, boolean p2)

public final void log(String message, int p1, byte p2)

public final void log(String message, int p1, char p2)

public final void log(String message, int p1, double p2)

public final void log(String message, int p1, float p2)

public final void log(String message, int p1, int p2)

public final void log(String message, int p1, @Nullable() Object p2)

public final void log(String message, int p1, long p2)

public final void log(String message, int p1, short p2)

public final void log(String message, @Nullable() Object p1, boolean p2)

public final void log(String message, @Nullable() Object p1, byte p2)

public final void log(String message, @Nullable() Object p1, char p2)

public final void log(String message, @Nullable() Object p1, double p2)

public final void log(String message, @Nullable() Object p1, float p2)

public final void log(String message, @Nullable() Object p1, int p2)

public final void log(String message, @Nullable() Object p1, @Nullable() Object p2)

public final void log(String message, @Nullable() Object p1, long p2)

public final void log(String message, @Nullable() Object p1, short p2)

public final void log(String message, long p1, boolean p2)

public final void log(String message, long p1, byte p2)

public final void log(String message, long p1, char p2)

public final void log(String message, long p1, double p2)

public final void log(String message, long p1, float p2)

public final void log(String message, long p1, int p2)

public final void log(String message, long p1, @Nullable() Object p2)

public final void log(String message, long p1, long p2)

public final void log(String message, long p1, short p2)

public final void log(String message, short p1, boolean p2)

public final void log(String message, short p1, byte p2)

public final void log(String message, short p1, char p2)

public final void log(String message, short p1, double p2)

public final void log(String message, short p1, float p2)

public final void log(String message, short p1, int p2)

public final void log(String message, short p1, @Nullable() Object p2)

public final void log(String message, short p1, long p2)

public final void log(String message, short p1, short p2)

public final void log(String message, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3)

public final void log(String message, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3, @Nullable() Object p4)

public final void log(String msg, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3, @Nullable() Object p4, @Nullable() Object p5)

public final void log(String msg, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3, @Nullable() Object p4, @Nullable() Object p5, @Nullable() Object p6)

public final void log(String msg, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3, @Nullable() Object p4, @Nullable() Object p5, @Nullable() Object p6, @Nullable() Object p7)

public final void log(String msg, @Nullable() Object p1, @Nullable() Object p2, @Nullable() Object p3, @Nullable() Object p4, @Nullable() Object p5, @Nullable() Object p6, @Nullable() Object p7, @Nullable() Object p8)

Logs a message with formatted arguments (see log for details).

public final void log(String message, @Nullable() Object p1)

Logs a formatted representation of the given parameter, using the specified message template.

logVarargs

public final void logVarargs(String message, @Nullable() Array<Object> params)

Logs a formatted representation of values in the given array, using the specified message template.

noOp

protected abstract API noOp()

Returns the constant no-op logging API, which can be returned by fluent methods in extended logging contexts to efficiently disable logging.

onAverageEvery

public final API onAverageEvery(int n)

Modifies the current log statement to be emitted with likelihood 1 in n.

per

public API per(LoggingScopeProvider scopeProvider)

Aggregates stateful logging with respect to a scoped context determined by the given scope provider.

public final API per(Enum<? extends Object> key)

Aggregates stateful logging with respect to the given enum value.

public API per<T>(@Nullable() @Nullable() T key, LogPerBucketingStrategy<? extends Object> strategy)

Aggregates stateful logging with respect to a given key.

postProcess

protected boolean postProcess(@Nullable() @Nullable() LogSiteKey logSiteKey)

A callback which can be overridden to implement post processing of logging contexts prior to passing them to the backend.

removeMetadata

protected final void removeMetadata(FloggerMetadataKey<? extends Object> key)

Removes all key/value pairs with the specified key.

updateRateLimiterStatus

protected final boolean updateRateLimiterStatus(@Nullable() @Nullable() RateLimitStatus status)

Callback to allow custom log contexts to apply additional rate limiting behaviour.

wasForced

public final boolean wasForced()

Returns whether this log statement should be emitted regardless of its log level or any other properties.

with

public final API with(FloggerMetadataKey<Boolean> key)

Sets a boolean metadata key constant to true for this log statement in a structured way that is accessible to logger backends.

public final API with<T>(FloggerMetadataKey<T> key, @Nullable() @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.

withCause

public final API withCause(Throwable cause)

Associates a Throwable instance with the current log statement, to be interpreted as the cause of this statement.

withInjectedLogSite

public final API withInjectedLogSite(FloggerLogSite logSite)

Sets the log site for the current log statement.

public final API withInjectedLogSite(String internalClassName, String methodName, int encodedLineNumber, @Nullable() @Nullable() String sourceFileName)

Internal method not for public use.

withStackTrace

public API withStackTrace(StackSize size)

Creates a synthetic exception and attaches it as the "cause" of the log statement as a way to provide additional context for the logging call itself.

LogContext

See also

Constructors

Types

Properties

Functions