Class HistogramLogReader
- java.lang.Object
-
- org.HdrHistogram.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.
-
-
Field Summary
Fields Modifier and Type Field Description private boolean
absolute
private double
baseTimeSec
private HistogramLogScanner.EventHandler
handler
private EncodableHistogram
nextHistogram
private boolean
observedBaseTime
private boolean
observedStartTime
private double
rangeEndTimeSec
private double
rangeStartTimeSec
private HistogramLogScanner
scanner
private double
startTimeSec
-
Constructor Summary
Constructors Constructor Description HistogramLogReader(java.io.File inputFile)
Constructs a new HistogramLogReader that produces intervals read from the specified file.HistogramLogReader(java.io.InputStream inputStream)
Constructs a new HistogramLogReader that produces intervals read from the specified InputStream.HistogramLogReader(java.lang.String inputFileName)
Constructs a new HistogramLogReader that produces intervals read from the specified file name.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
close()
double
getStartTimeSec()
get the latest start time found in the file so far (or 0.0), per the log file format explained above.boolean
hasNext()
Indicates whether or not additional intervals may exist in the logEncodableHistogram
nextAbsoluteIntervalHistogram(double absoluteStartTimeSec, double absoluteEndTimeSec)
Read the next interval histogram from the log, if interval falls within an absolute time rangeEncodableHistogram
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.private EncodableHistogram
nextIntervalHistogram(double rangeStartTimeSec, double rangeEndTimeSec, boolean absolute)
-
-
-
Field Detail
-
scanner
private final HistogramLogScanner scanner
-
handler
private final HistogramLogScanner.EventHandler handler
-
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
-
nextHistogram
private EncodableHistogram nextHistogram
-
-
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 rangeReturns 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
-
-