org.HdrHistogram

Class HistogramLogReader

java.lang.Object

org.HdrHistogram.HistogramLogReader

public class HistogramLogReader
extends Object

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.

Constructor Summary

Constructors

Constructor and Description
HistogramLogReader(File inputFile) Constructs a new HistogramLogReader that produces intervals read from the specified file.
HistogramLogReader(InputStream inputStream) Constructs a new HistogramLogReader that produces intervals read from the specified InputStream.
HistogramLogReader(String inputFileName) Constructs a new HistogramLogReader that produces intervals read from the specified file name.

Method Summary

Modifier and Type	Method and Description
double	getStartTimeSec() get the latest start time found in the file so far (or 0.0), per the log file format explained above.
EncodableHistogram	nextAbsoluteIntervalHistogram(double absoluteStartTimeSec, double absoluteEndTimeSec) Read the next interval histogram from the log, if interval falls within an absolute time range
EncodableHistogram	nextIntervalHistogram() Read the next interval histogram from the log.
EncodableHistogram	nextIntervalHistogram(double startTimeSec, double endTimeSec) Read the next interval histogram from the log, if interval falls within a time range.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

HistogramLogReader

public HistogramLogReader(String inputFileName)
                   throws 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:

FileNotFoundException - when unable to find inputFileName

HistogramLogReader

public HistogramLogReader(InputStream inputStream)

Constructs a new HistogramLogReader that produces intervals read from the specified InputStream.

Parameters:

inputStream - The InputStream to read from

HistogramLogReader

public HistogramLogReader(File inputFile)
                   throws FileNotFoundException

Constructs a new HistogramLogReader that produces intervals read from the specified file.

Parameters:

inputFile - The File to read from

Throws:

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.

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.

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 file, this method will return a null.

Returns:

a DecodedInterval, or a null if no appropriate interval found