Package org.kiwiproject.beta.slf4j

Class TimestampingLogger

  • @Beta
public class TimestampingLogger
extends Object
    A simple way to log timing information about a repeated operation.

    This is intended to be used for a single logical operation which contains multiple steps, or for the same operation repeated over a collection. For example, an order operation with separate steps to find a user, create a new order linked to the user, and insert the order to a database. Or, some kind of data migration that loops over records in a source database table and writes to a new target database table.

    Use the single argument constructor to create an instance with default values. Otherwise, use the builder() to customize the behavior.

    The options provided via the builder are:

    Options provided via the builder
    Name Default Description
    logger (None) The SLF4J Logger to use. This is required.
    initialTimestamp 0 The nanoseconds to use as the starting point against which the next elapsed time should be measured, e.g. using System.nanoTime(). When this is zero, the first elapsed log message will be the initialMessage to indicate there is not a previous timestamp against which to measure. If you want to start measurement from the time a TimestampingLogger is created, set it to System.nanoTime().
    elapsedTimeTemplate "[elapsed time since previous: {} nanoseconds / {} millis]" The template to use when logging elapsed time messages. Uses KiwiStrings.format(String, Object...) to format messages.
    argumentTransformer new Object[] { elapsedNanos, elapsedMillis } A BiFunction that accepts nanoseconds and the log count, and which should convert those into arguments for the elapsedTimeTemplate. If you customize the elapsedTimeTemplate then this should return an array with the same number of elements as there as placeholders in the template. For example, the default template has two placeholders, for nanos and millis, and the default transformer returns an array with two elements, the elapsed nanos and millis. The log count is simply the number of times the elapsed time has been logged. It is not used by the default elapsedTimeTemplate.
    skipInitialMessage false When true, no elapsed time message is logged the first time an elapsed time is logged. By default, an initial message will be printed, unless an initialTimestamp is supplied. In that case, the first elapsed time message will use the elapsedTimeTemplate.
    initialMessage "[elapsed time since previous: N/A (no previous timestamp)]" The message to log the first time elapsed time is logged, assuming the previous timestamp is zero.

    Currently, this is intended only to be used within a single thread.

    • Constructor Detail

      • TimestampingLogger

        public TimestampingLogger​(org.slf4j.Logger logger)
        Create a new instance with default values using the given Logger.

    • Method Detail

      • traceLogElapsed

        public void traceLogElapsed​(String message,
                            Object... args)
        Logs a message and elapsed time message at TRACE level.
        Parameters:
        message - the message or message template
        args - the arguments to the message template, if any
        See Also:
        logElapsed(Level, String, Object...)

      • debugLogElapsed

        public void debugLogElapsed​(String message,
                            Object... args)
        Logs a message and elapsed time message at DEBUG level.
        Parameters:
        message - the message or message template
        args - the arguments to the message template, if any
        See Also:
        logElapsed(Level, String, Object...)

      • logElapsed

        public void logElapsed​(org.slf4j.event.Level level,
                       String message,
                       Object... args)
        Logs the given message, and then logs the elapsed time since the previous log. This results in two separate log messages.
        Parameters:
        level - the level at which to log the message and elapsed time message
        message - the message or message template
        args - the arguments to the message template, if any

      • traceLogAppendingElapsed

        public void traceLogAppendingElapsed​(String message,
                                     Object... args)
        Logs a message at TRACE level and appends an elapsed time message.
        Parameters:
        message - the message or message template
        args - the arguments to the message template, if any
        See Also:
        logAppendingElapsed(Level, String, Object...)

      • debugLogAppendingElapsed

        public void debugLogAppendingElapsed​(String message,
                                     Object... args)
        Logs a message at DEBUG level and appends an elapsed time message.
        Parameters:
        message - the message or message template
        args - the arguments to the message template, if any
        See Also:
        logAppendingElapsed(Level, String, Object...)

      • logAppendingElapsed

        public void logAppendingElapsed​(org.slf4j.event.Level level,
                                String message,
                                Object... args)
        Logs a message at the given level and appends an elapsed time message. This results in a single log message containing the original message followed by the elapsed time message.
        Parameters:
        level - the level at which to log the message and elapsed time message
        message - the message or message template
        args - the arguments to the message template, if any