Package io.spine.logging.flogger.context

Class ScopedLoggingContexts

    • Method Detail

      • newContext

        public static ScopedLoggingContext.Builder newContext()
        Creates a new ScopedLoggingContext.Builder to which additional logging metadata can be attached before being installed or used to wrap some existing code. 
        
 Foo result = ScopedLoggingContexts.newContext()
     .withTags(Tags.of("my_tag", someValue))
     .call(MyClass::doFoo);

      • addTags

        @CanIgnoreReturnValue
public static boolean addTags​(Tags tags)
        Adds tags by modifying the current context (if one exists).

        Warning: It is always better to create a new context via newContext() rather than attempting to modify an existing context. In order of preference you should:

        1. Call or wrap a new context with metadata added to it.
        2. install() a new context and close it when you it exits (e.g. if you are using callbacks to listen to state changes in a task). However it is vital that the returned ScopedLoggingContext.LogContextCloseable is always closed.
        3. Call this method and check that it succeeded (e.g. logging a warning if it fails).

        The given tags are merged with those of the modifed context but existing tags will not be overwritten or removed. This is deliberate since two pieces of code may not know about each other and could accidentally use the same tag name; in that situation it's important that both tag values are preserved.

        Furthermore, the types of data allowed for tag values are strictly controlled. This is also very deliberate since these tags must be efficiently added to every log statement and so it's important that they resulting string representation is reliably cacheable and can be calculated without invoking arbitrary code (e.g. the toString() method of some unknown user type).

        Returns:
        false if there is no current context, or scoped contexts are not supported.

      • addMetadata

        @CanIgnoreReturnValue
public static <T> boolean addMetadata​(FloggerMetadataKey<T> key,
                                      T value)
        Adds a single metadata key/value pair to the current context.

        Warning: It is always better to create a new context via newContext() rather than attempting to modify an existing context. In order of preference you should:

        1. Call or wrap a new context with metadata added to it.
        2. install() a new context and close it when you it exits (e.g. if you are using callbacks to listen to state changes in a task). However it is vital that the returned ScopedLoggingContext.LogContextCloseable is always closed.
        3. Call this method and check that it succeeded (e.g. logging a warning if it fails).

        Unlike Tags, which have a well defined value ordering, independent of the order in which values were added, context metadata preserves the order of addition. As such, it is not advised to add values for the same metadata key from multiple threads, since that may create non-deterministic ordering. It is recommended (where possible) to add metadata when building a new context, rather than adding it to context visible to multiple threads.

      • applyLogLevelMap

        @CanIgnoreReturnValue
public static boolean applyLogLevelMap​(LogLevelMap logLevelMap)
        Applies the given log level map to the current context.

        Warning: It is always better to create a new context via newContext() rather than attempting to modify an existing context. In order of preference you should:

        1. Call or wrap a new context with metadata added to it.
        2. install() a new context and close it when you it exits (e.g. if you are using callbacks to listen to state changes in a task). However it is vital that the returned ScopedLoggingContext.LogContextCloseable is always closed.
        3. Call this method and check that it succeeded (e.g. logging a warning if it fails).
        Log level settings are merged with any existing setting from the current (or parent) contexts such that logging will be enabled for a log statement if:
        • It was enabled by the given map.
        • It was already enabled by the current context.

        The effects of this call will be undone only when the current context terminates.

        Returns:
        false if there is no current context, or scoped contexts are not supported.