org.HdrHistogram
Class HistogramLogWriter

java.lang.Object
  org.HdrHistogram.HistogramLogWriter

public class HistogramLogWriter
extends 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.

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

HistogramLogWriter(File outputFile)
Constructs a new HistogramLogWriter that will write into the specified file.

HistogramLogWriter(OutputStream outputStream)
Constructs a new HistogramLogWriter that will write into the specified output stream.

HistogramLogWriter(PrintStream printStream)
Constructs a new HistogramLogWriter that will write into the specified print stream.

HistogramLogWriter(String outputFileName)
Constructs a new HistogramLogWriter around a newly created file with the specified file name.

Method Summary

void	outputComment(String comment) Log a comment to the log.
void	outputIntervalHistogram(double startTimeStampSec, double endTimeStampSec, EncodableHistogram histogram) Output an interval histogram, with the given timestamp.
void	outputIntervalHistogram(double startTimeStampSec, double endTimeStampSec, EncodableHistogram histogram, double maxValueUnitRatio) Output an interval histogram, with the given timestamp and a configurable maxValueUnitRatio.
void	outputIntervalHistogram(EncodableHistogram histogram) Output an interval histogram, using the timestamp indicated in 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.

Methods inherited from class java.lang.Object

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

Constructor Detail

HistogramLogWriter

public HistogramLogWriter(String outputFileName)
                   throws 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:

FileNotFoundException - when unable to open outputFileName

HistogramLogWriter

public HistogramLogWriter(File outputFile)
                   throws FileNotFoundException

Constructs a new HistogramLogWriter that will write into the specified file.

Parameters:

outputFile - The File to write to

Throws:

FileNotFoundException - when unable to open outputFile

HistogramLogWriter

public HistogramLogWriter(OutputStream outputStream)

Constructs a new HistogramLogWriter that will write into the specified output stream.

Parameters:

outputStream - The OutputStream to write to

HistogramLogWriter

public HistogramLogWriter(PrintStream printStream)

Constructs a new HistogramLogWriter that will write into the specified print stream.

Parameters:

printStream - The PrintStream to write to

Method Detail

outputIntervalHistogram

public void outputIntervalHistogram(double startTimeStampSec,
                                    double endTimeStampSec,
                                    EncodableHistogram histogram,
                                    double maxValueUnitRatio)

Output an interval histogram, with the given timestamp and a configurable maxValueUnitRatio. (note that the specified timestamp will be used, and the timestamp 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. (note that the specified timestamp will be used, and the timestamp 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 timestamp indicated in the histogram. 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:

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)

outputComment

public void outputComment(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.