Package com.google.common.flogger.backend

Class SimpleMessageFormatter

  • public final class SimpleMessageFormatter
extends java.lang.Object
    Helper class for formatting LogData as text. This class is useful for any logging backend which performs unstructured, text only, logging. Note however that it makes several assumptions regarding metadata and formatting, which may not apply to every text based logging backend.

    This primarily exists to support both the JDK logging classes and text only Android backends. Code in here may be factored out as necessary to support other use cases in future.

    If a text based logger backend is not performance critical, then it should just append the log message and metadata to a local buffer. For example: 

    
 MetadataProcessor metadata =
     MetadataProcessor.forScopeAndLogSite(Platform.getInjectedMetadata(), logData.getMetadata());
 StringBuilder buffer = new StringBuilder();
 // Optional prefix goes here...
 SimpleMessageFormatter.getDefaultFormatter().append(logData, metadata, buffer);
 // Optional suffix goes here...
 String message = buffer.toString();

    If additional metadata keys, other than the cause are to be omitted, then getSimpleFormatterIgnoring(MetadataKey...) can be used to obtain a static formatter, instead of using the default.

    • Method Detail

      • getDefaultFormatter

        public static LogMessageFormatter getDefaultFormatter()
        Returns the singleton default log message formatter. This formats log messages in the form: 
        
 Log message [CONTEXT key="value" id=42 ]

        with context from the log data and scope, merged together in a sequence of key/value pairs after the formatted message. If the log message is long or multi-line, then the context suffix will be formatted on a single separate line.

        The cause is omitted from the context section, since it's handled separately by most logger backends and not considered part of the formatted message. Other internal metadata keys may also be suppressed.

      • getSimpleFormatterIgnoring

        public static LogMessageFormatter getSimpleFormatterIgnoring​(MetadataKey<?>... extraIgnoredKeys)
        Returns a log message formatter which formats log messages in the form: 
        
 Log message [CONTEXT key="value" id=42 ]

        with context from the log data and scope, merged together in a sequence of key/value pairs after the formatted message. If the log message is long or multi-line, then the context suffix will be formatted on a single separate line.

        This differs from the default formatter because it allows the caller to specify additional metadata keys to be omitted from the formatted context. By default the cause is always omitted from the context section, since it's handled separately by most logger backends and almost never expected to be part of the formatted message. Other internal metadata keys may also be suppressed.

      • appendContext

        public static java.lang.StringBuilder appendContext​(MetadataProcessor metadataProcessor,
                                                    MetadataHandler<MetadataKey.KeyValueHandler> metadataHandler,
                                                    java.lang.StringBuilder buffer)
        Appends formatted context information to the given buffer using the supplied metadata handler. A custom metadata handler is useful if the logger backend wishes to:
        • Ignore more than just the default set of metadata keys (currently just the "cause").
        • Intercept and capture metadata values for additional processing or logging control.
        Parameters:
        metadataProcessor - snapshot of the metadata to be processed (MetadataProcessor is reusable so passing one in can save repeated processing of the same metadata).
        metadataHandler - a metadata handler for intercepting and dispatching metadata during formatting.
        buffer - destination buffer into which the log message and metadata will be appended.
        Returns:
        the given destination buffer (for method chaining).

      • getLiteralLogMessage

        public static java.lang.String getLiteralLogMessage​(LogData logData)
        Returns the single literal value as a string. This method must never be called if the log data has arguments to be formatted.

        This method is designed to be paired with mustBeFormatted(LogData,MetadataProcessor,Set) and can always be safely called if that method returned false for the same log data.

        Parameters:
        logData - the log statement data.
        Returns:
        the single logged value as a string.
        Throws:
        java.lang.IllegalStateException - if the log data had arguments to be formatted (i.e. there was a template context).

      • mustBeFormatted

        public static boolean mustBeFormatted​(LogData logData,
                                      MetadataProcessor metadata,
                                      java.util.Set<MetadataKey<?>> keysToIgnore)
        An internal helper method for logger backends which are aggressively optimized for performance. This method is a best-effort optimization and should not be necessary for most implementations. It is not a stable API and may be removed at some point in the future.

        This method attempts to determine, for the given log data and log metadata, if the default message formatting performed by the other methods in this class would just result in the literal log message being used, with no additional formatting.

        If this method returns false then the literal log message can be obtained via getLiteralLogMessage(LogData), otherwise it must be formatted manually.

        By calling this class it is possible to more easily detect cases where using buffers to format the log message is not required. Obviously a logger backend my have its own reasons for needing buffering (e.g. prepending log site data) and those must also be taken into account.

        Parameters:
        logData - the log statement data.
        metadata - the metadata intended to be formatted with the log statement.
        keysToIgnore - a set of metadata keys which are known not to appear in the final formatted message.