Class TracingLogger

  • Direct Known Subclasses:
    TracingLogger.TracingLoggerImpl

    public abstract class TracingLogger
    extends java.lang.Object
    Low level Tracing support API. Use one instance per request.
    Since:
    2.3
    • Constructor Summary

      Constructors 
      Constructor Description
      TracingLogger()  
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      static TracingLogger create​(TracingLogger.Level threshold, java.lang.String loggerNameSuffix)
      Create new Tracing logger.
      static TracingLogger empty()
      Get an empty (no-op) tracing logger instance.
      abstract void flush​(javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.Object> headers)
      Stores collected tracing messages to response HTTP header.
      static TracingLogger getInstance​(PropertiesDelegate propertiesDelegate)
      Returns instance of TracingLogger associated with current request processing (propertiesDelegate).
      abstract boolean isLogEnabled​(TracingLogger.Event event)
      Test if a tracing support is enabled (according to propertiesDelegate setting) and if event can be logged (according to event.level and threshold level set).
      abstract void log​(TracingLogger.Event event, java.lang.Object... args)
      Try to log event according to event level and request context threshold level setting.
      abstract void logDuration​(TracingLogger.Event event, long fromTimestamp, java.lang.Object... args)
      Try to log event according to event level and request context threshold level setting.
      abstract long timestamp​(TracingLogger.Event event)
      If logging support is switched on for current request and event setting the method returns current timestamp in nanos.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • PROPERTY_NAME

        public static final java.lang.String PROPERTY_NAME
        TracingLogger instance is placed in request context properties under this name.
      • HEADER_TRACING_PREFIX

        private static final java.lang.String HEADER_TRACING_PREFIX
        HTTP header prefix.
        See Also:
        Constant Field Values
      • HEADER_THRESHOLD

        public static final java.lang.String HEADER_THRESHOLD
        Request header name to change application default tracing level.
        See Also:
        Constant Field Values
      • HEADER_ACCEPT

        public static final java.lang.String HEADER_ACCEPT
        Request header name to switch on request tracing. Make sense in case of tracing support enabled by ON_DEMAND value.
        See Also:
        Constant Field Values
      • HEADER_LOGGER

        public static final java.lang.String HEADER_LOGGER
        Request header name to set JDK logger name suffix to identify a request logs.
        See Also:
        Constant Field Values
      • HEADER_RESPONSE_FORMAT

        private static final java.lang.String HEADER_RESPONSE_FORMAT
        Response header name format.
        See Also:
        Constant Field Values
      • TRACING_LOGGER_NAME_PREFIX

        private static final java.lang.String TRACING_LOGGER_NAME_PREFIX
        JDK logger name prefix.
        See Also:
        Constant Field Values
      • DEFAULT_LOGGER_NAME_SUFFIX

        private static final java.lang.String DEFAULT_LOGGER_NAME_SUFFIX
        Default JDK logger name suffix. This can be overwrite by header HEADER_LOGGER.
        See Also:
        Constant Field Values
      • EMPTY

        private static final TracingLogger EMPTY
        Empty (no-op) tracing logger.
    • Constructor Detail

      • TracingLogger

        public TracingLogger()
    • Method Detail

      • getInstance

        public static TracingLogger getInstance​(PropertiesDelegate propertiesDelegate)
        Returns instance of TracingLogger associated with current request processing (propertiesDelegate).
        Parameters:
        propertiesDelegate - request associated runtime properties. Can be null if not running on server side.
        Returns:
        returns instance of TracingLogger from propertiesDelegate. Does not return null.
      • create

        public static TracingLogger create​(TracingLogger.Level threshold,
                                           java.lang.String loggerNameSuffix)
        Create new Tracing logger.
        Parameters:
        threshold - tracing level threshold.
        loggerNameSuffix - tracing logger name suffix.
        Returns:
        new tracing logger.
      • empty

        public static TracingLogger empty()
        Get an empty (no-op) tracing logger instance.
        Returns:
        empty tracing logger instance.
      • isLogEnabled

        public abstract boolean isLogEnabled​(TracingLogger.Event event)
        Test if a tracing support is enabled (according to propertiesDelegate setting) and if event can be logged (according to event.level and threshold level set).
        Parameters:
        event - event type to be tested
        Returns:
        true if event can be logged
      • log

        public abstract void log​(TracingLogger.Event event,
                                 java.lang.Object... args)
        Try to log event according to event level and request context threshold level setting.
        Parameters:
        event - event type to be logged
        args - message arguments (in relation to .Event#messageFormat()
      • logDuration

        public abstract void logDuration​(TracingLogger.Event event,
                                         long fromTimestamp,
                                         java.lang.Object... args)
        Try to log event according to event level and request context threshold level setting. If logging support is switched on for current request and event setting the method computes duration of event and log message. If fromTimestamp is not set (i.e. -1) then duration of event is 0.
        Parameters:
        event - event type to be logged
        fromTimestamp - logged event is running from the timestamp in nanos. -1 in case event has no duration
        args - message arguments (in relation to .Event#messageFormat()
      • timestamp

        public abstract long timestamp​(TracingLogger.Event event)
        If logging support is switched on for current request and event setting the method returns current timestamp in nanos.
        Parameters:
        event - event type to be logged
        Returns:
        Current timestamp in nanos or -1 if tracing is not enabled
      • flush

        public abstract void flush​(javax.ws.rs.core.MultivaluedMap<java.lang.String,​java.lang.Object> headers)
        Stores collected tracing messages to response HTTP header.
        Parameters:
        headers - message headers.