Class HistogramLogReader

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

    public class HistogramLogReader
    extends java.lang.Object
    implements java.io.Closeable
    A histogram log reader.

    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.

    Histogram log format:

    A histogram log file consists of text lines. Lines beginning with the "#" character are optional and treated as comments. Lines containing the legend (starting with "Timestamp") are also optional and ignored in parsing the histogram log. All other lines must be valid interval description lines. Text fields are delimited by commas, spaces.

    A valid interval description line contains an optional Tag=tagString text field, followed by an interval description.

    A valid interval description must contain exactly four text fields:

    • StartTimestamp: The first field must contain a number parse-able as a Double value, representing the start timestamp of the interval in seconds.
    • intervalLength: The second field must contain a number parse-able as a Double value, representing the length of the interval in seconds.
    • Interval_Max: The third field must contain a number parse-able as a Double value, which generally represents the maximum value of the interval histogram.
    • Interval_Compressed_Histogram: The fourth field must contain a text field parse-able as a Base64 text representation of a compressed HdrHistogram.
    The log file may contain an optional indication of a starting time. Starting time is indicated using a special comments starting with "#[StartTime: " and followed by a number parse-able as a double, representing the start time (in seconds) that may be added to timestamps in the file to determine an absolute timestamp (e.g. since the epoch) for each interval.
    • Field Detail

      • startTimeSec

        private double startTimeSec
      • observedStartTime

        private boolean observedStartTime
      • baseTimeSec

        private double baseTimeSec
      • observedBaseTime

        private boolean observedBaseTime
      • absolute

        private boolean absolute
      • rangeStartTimeSec

        private double rangeStartTimeSec
      • rangeEndTimeSec

        private double rangeEndTimeSec
    • Constructor Detail

      • HistogramLogReader

        public HistogramLogReader​(java.lang.String inputFileName)
                           throws java.io.FileNotFoundException
        Constructs a new HistogramLogReader that produces intervals read from the specified file name.
        Parameters:
        inputFileName - The name of the file to read from
        Throws:
        java.io.FileNotFoundException - when unable to find inputFileName
      • HistogramLogReader

        public HistogramLogReader​(java.io.InputStream inputStream)
        Constructs a new HistogramLogReader that produces intervals read from the specified InputStream.
        Parameters:
        inputStream - The InputStream to read from
      • HistogramLogReader

        public HistogramLogReader​(java.io.File inputFile)
                           throws java.io.FileNotFoundException
        Constructs a new HistogramLogReader that produces intervals read from the specified file.
        Parameters:
        inputFile - The File to read from
        Throws:
        java.io.FileNotFoundException - when unable to find inputFile
    • Method Detail

      • getStartTimeSec

        public double getStartTimeSec()
        get the latest start time found in the file so far (or 0.0), per the log file format explained above. Assuming the "#[StartTime:" comment line precedes the actual intervals recorded in the file, getStartTimeSec() can be safely used after each interval is read to determine's the offset of that interval's timestamp from the epoch.
        Returns:
        latest Start Time found in the file (or 0.0 if non found)
      • nextIntervalHistogram

        public EncodableHistogram nextIntervalHistogram​(double startTimeSec,
                                                        double endTimeSec)
        Read the next interval histogram from the log, if interval falls within a time range.

        Returns a histogram object if an interval line was found with an associated start timestamp value that falls between startTimeSec and endTimeSec, or null if no such interval line is found. Note that the range is assumed to be in seconds relative to the actual timestamp value found in each interval line in the log, and not in absolute time.

        Timestamps are assumed to appear in order in the log file, and as such this method will return a null upon encountering a timestamp larger than rangeEndTimeSec.

        The histogram returned will have it's timestamp set to the absolute timestamp calculated from adding the interval's indicated timestamp value to the latest [optional] start time found in the log.

        Upon encountering any unexpected format errors in reading the next interval from the file, this method will return a null. Use hasNext() to determine whether or not additional intervals may be available for reading in the log input.

        Parameters:
        startTimeSec - The (non-absolute time) start of the expected time range, in seconds.
        endTimeSec - The (non-absolute time) end of the expected time range, in seconds.
        Returns:
        a histogram, or a null if no appropriate interval found
      • nextAbsoluteIntervalHistogram

        public EncodableHistogram nextAbsoluteIntervalHistogram​(double absoluteStartTimeSec,
                                                                double absoluteEndTimeSec)
        Read the next interval histogram from the log, if interval falls within an absolute time range

        Returns a histogram object if an interval line was found with an associated absolute start timestamp value that falls between absoluteStartTimeSec and absoluteEndTimeSec, or null if no such interval line is found.

        Timestamps are assumed to appear in order in the log file, and as such this method will return a null upon encountering a timestamp larger than rangeEndTimeSec.

        The histogram returned will have it's timestamp set to the absolute timestamp calculated from adding the interval's indicated timestamp value to the latest [optional] start time found in the log.

        Absolute timestamps are calculated by adding the timestamp found with the recorded interval to the [latest, optional] start time found in the log. The start time is indicated in the log with a "#[StartTime: " followed by the start time in seconds.

        Upon encountering any unexpected format errors in reading the next interval from the file, this method will return a null. Use hasNext() to determine whether or not additional intervals may be available for reading in the log input.

        Parameters:
        absoluteStartTimeSec - The (absolute time) start of the expected time range, in seconds.
        absoluteEndTimeSec - The (absolute time) end of the expected time range, in seconds.
        Returns:
        A histogram, or a null if no appropriate interval found
      • nextIntervalHistogram

        public EncodableHistogram nextIntervalHistogram()
        Read the next interval histogram from the log. Returns a Histogram object if an interval line was found, or null if not.

        Upon encountering any unexpected format errors in reading the next interval from the input, this method will return a null. Use hasNext() to determine whether or not additional intervals may be available for reading in the log input.

        Returns:
        a DecodedInterval, or a null if no appropriately formatted interval was found
      • nextIntervalHistogram

        private EncodableHistogram nextIntervalHistogram​(double rangeStartTimeSec,
                                                         double rangeEndTimeSec,
                                                         boolean absolute)
      • hasNext

        public boolean hasNext()
        Indicates whether or not additional intervals may exist in the log
        Returns:
        true if additional intervals may exist in the log
      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable