HdrHistogram 2.1.12 · org.HdrHistogram.HistogramLogReader

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 Summary

Modifier and Type	Field and Description
private boolean	absolute
private double	baseTimeSec
private final HistogramLogScanner.EventHandler	handler
private EncodableHistogram	nextHistogram
private boolean	observedBaseTime
private boolean	observedStartTime
private double	rangeEndTimeSec
private double	rangeStartTimeSec
private final HistogramLogScanner	scanner
private double	startTimeSec

Constructor Summary

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

Method Summary

Modifier and Type	Method and Description
public void	close() Implements java.io.Closeable.close. Closes this stream and releases any system resources associated with it.
public double	Returns: latest Start Time found in the file (or 0.0 if non found) getStartTimeSec() get the latest start time found in the file so far (or 0.0), per the log file format explained above.
public boolean	Returns: true if additional intervals may exist in the log hasNext() Indicates whether or not additional intervals may exist in the log
public EncodableHistogram	Returns: A histogram, or a null if no appropriate interval found nextAbsoluteIntervalHistogram(final double The (absolute time) start of the expected time range, in seconds. absoluteStartTimeSec, final double The (absolute time) end of the expected time range, in seconds. 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.
public EncodableHistogram	Returns: a histogram, or a null if no appropriate interval found nextIntervalHistogram(final double The (non-absolute time) start of the expected time range, in seconds. startTimeSec, final double The (non-absolute time) end of the expected time range, in seconds. endTimeSec) Read the next interval histogram from the log, if interval falls within a time range.
public EncodableHistogram	Returns: a DecodedInterval, or a null if no appropriately formatted interval was found nextIntervalHistogram() Read the next interval histogram from the log.
private EncodableHistogram	nextIntervalHistogram(final double rangeStartTimeSec, final double rangeEndTimeSec, boolean absolute)

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

absolute	back to summary
private boolean absolute

baseTimeSec	back to summary
private double baseTimeSec

handler	back to summary
private final HistogramLogScanner.EventHandler handler

nextHistogram	back to summary
private EncodableHistogram nextHistogram

observedBaseTime	back to summary
private boolean observedBaseTime

observedStartTime	back to summary
private boolean observedStartTime

rangeEndTimeSec	back to summary
private double rangeEndTimeSec

rangeStartTimeSec	back to summary
private double rangeStartTimeSec

scanner	back to summary
private final HistogramLogScanner scanner

startTimeSec	back to summary
private double startTimeSec

Constructor Detail

HistogramLogReader	back to summary
public HistogramLogReader(final String inputFileName) throws FileNotFoundException Constructs a new HistogramLogReader that produces intervals read from the specified file name. Parameters inputFileName:String The name of the file to read from Exceptions FileNotFoundException: when unable to find inputFileName

HistogramLogReader

back to summary

public HistogramLogReader(final String inputFileName) throws FileNotFoundException

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

Parameters

inputFileName:String: The name of the file to read from

Exceptions

FileNotFoundException:: when unable to find inputFileName

HistogramLogReader	back to summary
public HistogramLogReader(final InputStream inputStream) Constructs a new HistogramLogReader that produces intervals read from the specified InputStream. Parameters inputStream:InputStream The InputStream to read from

HistogramLogReader

back to summary

public HistogramLogReader(final InputStream inputStream)

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

Parameters

inputStream:InputStream: The InputStream to read from

HistogramLogReader	back to summary
public HistogramLogReader(final File inputFile) throws FileNotFoundException Constructs a new HistogramLogReader that produces intervals read from the specified file. Parameters inputFile:File The File to read from Exceptions FileNotFoundException: when unable to find inputFile

HistogramLogReader

back to summary

public HistogramLogReader(final File inputFile) throws FileNotFoundException

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

Parameters

inputFile:File: The File to read from

Exceptions

FileNotFoundException:: when unable to find inputFile

Method Detail

close back to summary

close	back to summary
public void close() Implements java.io.Closeable.close. Doc from java.io.Closeable.close. Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect. As noted in `AutoCloseable#close()`, cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the `Closeable` as closed, prior to throwing the `IOException`. Annotations @Override

public void close()

Implements java.io.Closeable.close.

Doc from java.io.Closeable.close.

Closes this stream and releases any system resources associated with it. If the stream is already closed then invoking this method has no effect.

As noted in AutoCloseable#close(), cases where the close may fail require careful attention. It is strongly advised to relinquish the underlying resources and to internally mark the Closeable as closed, prior to throwing the IOException.

Annotations

@Override

getStartTimeSec	back to summary
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:double latest Start Time found in the file (or 0.0 if non found)

getStartTimeSec

back to summary

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:double: latest Start Time found in the file (or 0.0 if non found)

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

hasNext

back to summary

public boolean hasNext()

Indicates whether or not additional intervals may exist in the log

Returns:boolean: true if additional intervals may exist in the log

nextAbsoluteIntervalHistogram back to summary

nextAbsoluteIntervalHistogram	back to summary
public EncodableHistogram nextAbsoluteIntervalHistogram(final double absoluteStartTimeSec, final 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:double The (absolute time) start of the expected time range, in seconds. absoluteEndTimeSec:double The (absolute time) end of the expected time range, in seconds. Returns:EncodableHistogram A histogram, or a null if no appropriate interval found

public EncodableHistogram nextAbsoluteIntervalHistogram(final double absoluteStartTimeSec, final 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:double: The (absolute time) start of the expected time range, in seconds.
absoluteEndTimeSec:double: The (absolute time) end of the expected time range, in seconds.

Returns:EncodableHistogram

A histogram, or a null if no appropriate interval found

nextIntervalHistogram back to summary

nextIntervalHistogram	back to summary
public EncodableHistogram nextIntervalHistogram(final double startTimeSec, final 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:double The (non-absolute time) start of the expected time range, in seconds. endTimeSec:double The (non-absolute time) end of the expected time range, in seconds. Returns:EncodableHistogram a histogram, or a null if no appropriate interval found

public EncodableHistogram nextIntervalHistogram(final double startTimeSec, final 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.

Parameters

startTimeSec:double: The (non-absolute time) start of the expected time range, in seconds.
endTimeSec:double: The (non-absolute time) end of the expected time range, in seconds.

Returns:EncodableHistogram

a histogram, or a null if no appropriate interval found

nextIntervalHistogram back to summary

nextIntervalHistogram	back to summary
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:EncodableHistogram a DecodedInterval, or a null if no appropriately formatted interval was found

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:EncodableHistogram: a DecodedInterval, or a null if no appropriately formatted interval was found

nextIntervalHistogram	back to summary
private EncodableHistogram nextIntervalHistogram(final double rangeStartTimeSec, final double rangeEndTimeSec, boolean absolute)

public Class HistogramLogReader

Histogram log format:

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail