Class HistogramLogWriter


  • public class HistogramLogWriter
    extends java.lang.Object
    A histogram log writer.

    A Histogram logs are used to capture full fidelity, per-time-interval histograms of a recorded value.

    For example, a histogram log can be used to capture high fidelity reaction-time logs for some measured system or subsystem component. Such a log would capture a full reaction time histogram for each logged interval, and could be used to later reconstruct a full HdrHistogram of the measured reaction time behavior for any arbitrary time range within the log, by adding [only] the relevant interval histograms.

    This log writer will produce histogram logs that adhere to the histogram log format (see {HistogramLogReader for log format details). Optional comments, start time, legend, and format version can be logged.

    The log writer will use the

    By convention, it is typical for the logging application to use a comment to indicate the logging application at the head of the log, followed by the log format version, a start time, and a legend (in that order).

    • Constructor Summary

      Constructors 
      Constructor Description
      HistogramLogWriter​(java.io.File outputFile)
      Constructs a new HistogramLogWriter that will write into the specified file.
      HistogramLogWriter​(java.io.OutputStream outputStream)
      Constructs a new HistogramLogWriter that will write into the specified output stream.
      HistogramLogWriter​(java.io.PrintStream printStream)
      Constructs a new HistogramLogWriter that will write into the specified print stream.
      HistogramLogWriter​(java.lang.String outputFileName)
      Constructs a new HistogramLogWriter around a newly created file with the specified file name.
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()
      Closes the file or output stream for this log writer.
      long getBaseTime()
      return the current base time offset (see setBaseTime(long)).
      void outputBaseTime​(long baseTimeMsec)
      Log a base time in the log.
      void outputComment​(java.lang.String comment)
      Log a comment to the log.
      void outputIntervalHistogram​(double startTimeStampSec, double endTimeStampSec, EncodableHistogram histogram)
      Output an interval histogram, with the given timestamp information, and the [optional] tag associated with the histogram.
      void outputIntervalHistogram​(double startTimeStampSec, double endTimeStampSec, EncodableHistogram histogram, double maxValueUnitRatio)
      Output an interval histogram, with the given timestamp information and the [optional] tag associated with the histogram, using a configurable maxValueUnitRatio.
      void outputIntervalHistogram​(EncodableHistogram histogram)
      Output an interval histogram, using the start/end timestamp indicated in the histogram, and the [optional] tag associated with the histogram.
      void outputLegend()
      Output a legend line to the log.
      void outputLogFormatVersion()
      Output a log format version to the log.
      void outputStartTime​(long startTimeMsec)
      Log a start time in the log.
      void setBaseTime​(long baseTimeMsec)
      Set a base time to subtract from supplied histogram start/end timestamps when logging based on histogram timestamps.
      • Methods inherited from class java.lang.Object

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

      • HISTOGRAM_LOG_FORMAT_VERSION

        private static final java.lang.String HISTOGRAM_LOG_FORMAT_VERSION
        See Also:
        Constant Field Values
      • containsDelimeterPattern

        private static java.util.regex.Pattern containsDelimeterPattern
      • containsDelimeterMatcher

        private java.util.regex.Matcher containsDelimeterMatcher
      • log

        private final java.io.PrintStream log
      • targetBuffer

        private java.nio.ByteBuffer targetBuffer
      • baseTime

        private long baseTime
    • Constructor Detail

      • HistogramLogWriter

        public HistogramLogWriter​(java.lang.String outputFileName)
                           throws java.io.FileNotFoundException
        Constructs a new HistogramLogWriter around a newly created file with the specified file name.
        Parameters:
        outputFileName - The name of the file to create
        Throws:
        java.io.FileNotFoundException - when unable to open outputFileName
      • HistogramLogWriter

        public HistogramLogWriter​(java.io.File outputFile)
                           throws java.io.FileNotFoundException
        Constructs a new HistogramLogWriter that will write into the specified file.
        Parameters:
        outputFile - The File to write to
        Throws:
        java.io.FileNotFoundException - when unable to open outputFile
      • HistogramLogWriter

        public HistogramLogWriter​(java.io.OutputStream outputStream)
        Constructs a new HistogramLogWriter that will write into the specified output stream.
        Parameters:
        outputStream - The OutputStream to write to
      • HistogramLogWriter

        public HistogramLogWriter​(java.io.PrintStream printStream)
        Constructs a new HistogramLogWriter that will write into the specified print stream.
        Parameters:
        printStream - The PrintStream to write to
    • Method Detail

      • close

        public void close()
        Closes the file or output stream for this log writer.
      • outputIntervalHistogram

        public void outputIntervalHistogram​(double startTimeStampSec,
                                            double endTimeStampSec,
                                            EncodableHistogram histogram,
                                            double maxValueUnitRatio)
        Output an interval histogram, with the given timestamp information and the [optional] tag associated with the histogram, using a configurable maxValueUnitRatio. (note that the specified timestamp information will be used, and the timestamp information in the actual histogram will be ignored). The max value reported with the interval line will be scaled by the given maxValueUnitRatio.
        Parameters:
        startTimeStampSec - The start timestamp to log with the interval histogram, in seconds.
        endTimeStampSec - The end timestamp to log with the interval histogram, in seconds.
        histogram - The interval histogram to log.
        maxValueUnitRatio - The ratio by which to divide the histogram's max value when reporting on it.
      • outputIntervalHistogram

        public void outputIntervalHistogram​(double startTimeStampSec,
                                            double endTimeStampSec,
                                            EncodableHistogram histogram)
        Output an interval histogram, with the given timestamp information, and the [optional] tag associated with the histogram. (note that the specified timestamp information will be used, and the timestamp information in the actual histogram will be ignored). The max value in the histogram will be reported scaled down by a default maxValueUnitRatio of 1,000,000 (which is the msec : nsec ratio). Caller should use the direct form specifying maxValueUnitRatio some other ratio is needed for the max value output.
        Parameters:
        startTimeStampSec - The start timestamp to log with the interval histogram, in seconds.
        endTimeStampSec - The end timestamp to log with the interval histogram, in seconds.
        histogram - The interval histogram to log.
      • outputIntervalHistogram

        public void outputIntervalHistogram​(EncodableHistogram histogram)
        Output an interval histogram, using the start/end timestamp indicated in the histogram, and the [optional] tag associated with the histogram. The histogram start and end timestamps are assumed to be in msec units. Logging will be in seconds, realtive by a base time (if set via setBaseTime(long)). The default base time is 0.

        By covention, histogram start/end time are generally stamped with absolute times in msec since the epoch. For logging with absolute time stamps, the base time would remain zero. For logging with relative time stamps (time since a start point), the base time should be set with setBaseTime(long).

        The max value in the histogram will be reported scaled down by a default maxValueUnitRatio of 1,000,000 (which is the msec : nsec ratio). Caller should use the direct form specifying maxValueUnitRatio if some other ratio is needed for the max value output.

        Parameters:
        histogram - The interval histogram to log.
      • outputStartTime

        public void outputStartTime​(long startTimeMsec)
        Log a start time in the log.
        Parameters:
        startTimeMsec - time (in milliseconds) since the absolute start time (the epoch)
      • outputBaseTime

        public void outputBaseTime​(long baseTimeMsec)
        Log a base time in the log.
        Parameters:
        baseTimeMsec - time (in milliseconds) since the absolute start time (the epoch)
      • outputComment

        public void outputComment​(java.lang.String comment)
        Log a comment to the log. Comments will be preceded with with the '#' character.
        Parameters:
        comment - the comment string.
      • outputLegend

        public void outputLegend()
        Output a legend line to the log.
      • outputLogFormatVersion

        public void outputLogFormatVersion()
        Output a log format version to the log.
      • setBaseTime

        public void setBaseTime​(long baseTimeMsec)
        Set a base time to subtract from supplied histogram start/end timestamps when logging based on histogram timestamps. Base time is expected to be in msec since the epoch, as histogram start/end times are typically stamped with absolute times in msec since the epoch.
        Parameters:
        baseTimeMsec - base time to calculate timestamp deltas from
      • getBaseTime

        public long getBaseTime()
        return the current base time offset (see setBaseTime(long)).
        Returns:
        the current base time