Top Description Fields Constructors Methods
org.HdrHistogram

public Class HistogramLogWriter

extends Object
Class Inheritance
Imports
java.io.File, .FileNotFoundException, .OutputStream, .PrintStream, java.nio.ByteBuffer, java.util.Arrays, .Date, .Locale, java.util.regex.Matcher, .Pattern, java.util.zip.Deflater
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.

The log writer will use the

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).

Field Summary

Modifier and TypeField and Description
private long
baseTime

private Matcher
containsDelimeterMatcher

private static Pattern
containsDelimeterPattern

private static final String
HISTOGRAM_LOG_FORMAT_VERSION

private final PrintStream
log

private ByteBuffer
targetBuffer

Constructor Summary

AccessConstructor and Description
public
HistogramLogWriter(final String
The name of the file to create
outputFileName)

Constructs a new HistogramLogWriter around a newly created file with the specified file name.

public
HistogramLogWriter(final File
The File to write to
outputFile)

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

public
HistogramLogWriter(final OutputStream
The OutputStream to write to
outputStream)

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

public
HistogramLogWriter(final PrintStream
The PrintStream to write to
printStream)

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

Method Summary

Modifier and TypeMethod and Description
public void
close()

Closes the file or output stream for this log writer.

public long

Returns:

the current base time
getBaseTime()

return the current base time offset (see org.HdrHistogram.HistogramLogWriter#setBaseTime).

public void
outputBaseTime(final long
time (in milliseconds) since the absolute start time (the epoch)
baseTimeMsec)

Log a base time in the log.

public void
outputComment(final String
the comment string.
comment)

Log a comment to the log.

public synchronized void
outputIntervalHistogram(final double
The start timestamp to log with the interval histogram, in seconds.
startTimeStampSec, final double
The end timestamp to log with the interval histogram, in seconds.
endTimeStampSec, final EncodableHistogram
The interval histogram to log.
histogram, final double
The ratio by which to divide the histogram's max value when reporting on it.
maxValueUnitRatio)

Output an interval histogram, with the given timestamp information and the [optional] tag associated with the histogram, using a configurable maxValueUnitRatio.

public void
outputIntervalHistogram(final double
The start timestamp to log with the interval histogram, in seconds.
startTimeStampSec, final double
The end timestamp to log with the interval histogram, in seconds.
endTimeStampSec, final EncodableHistogram
The interval histogram to log.
histogram)

Output an interval histogram, with the given timestamp information, and the [optional] tag associated with the histogram.

public void
outputIntervalHistogram(final EncodableHistogram
The interval histogram to log.
histogram)

Output an interval histogram, using the start/end timestamp indicated in the histogram, and the [optional] tag associated with the histogram.

public void
outputLegend()

Output a legend line to the log.

public void
outputLogFormatVersion()

Output a log format version to the log.

public void
outputStartTime(final long
time (in milliseconds) since the absolute start time (the epoch)
startTimeMsec)

Log a start time in the log.

public void
setBaseTime(long
base time to calculate timestamp deltas from
baseTimeMsec)

Set a base time to subtract from supplied histogram start/end timestamps when logging based on histogram timestamps.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

baseTimeback to summary
private long baseTime
containsDelimeterMatcherback to summary
private Matcher containsDelimeterMatcher
containsDelimeterPatternback to summary
private static Pattern containsDelimeterPattern
HISTOGRAM_LOG_FORMAT_VERSIONback to summary
private static final String HISTOGRAM_LOG_FORMAT_VERSION
logback to summary
private final PrintStream log
targetBufferback to summary
private ByteBuffer targetBuffer

Constructor Detail

HistogramLogWriterback to summary
public HistogramLogWriter(final String outputFileName) throws FileNotFoundException

Constructs a new HistogramLogWriter around a newly created file with the specified file name.

Parameters
outputFileName:String

The name of the file to create

Exceptions
FileNotFoundException:
when unable to open outputFileName
HistogramLogWriterback to summary
public HistogramLogWriter(final File outputFile) throws FileNotFoundException

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

Parameters
outputFile:File

The File to write to

Exceptions
FileNotFoundException:
when unable to open outputFile
HistogramLogWriterback to summary
public HistogramLogWriter(final OutputStream outputStream)

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

Parameters
outputStream:OutputStream

The OutputStream to write to

HistogramLogWriterback to summary
public HistogramLogWriter(final PrintStream printStream)

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

Parameters
printStream:PrintStream

The PrintStream to write to

Method Detail

closeback to summary
public void close()

Closes the file or output stream for this log writer.

getBaseTimeback to summary
public long getBaseTime()

return the current base time offset (see org.HdrHistogram.HistogramLogWriter#setBaseTime).

Returns:long

the current base time

outputBaseTimeback to summary
public void outputBaseTime(final long baseTimeMsec)

Log a base time in the log.

Parameters
baseTimeMsec:long

time (in milliseconds) since the absolute start time (the epoch)

outputCommentback to summary
public void outputComment(final String comment)

Log a comment to the log. Comments will be preceded with with the '#' character.

Parameters
comment:String

the comment string.

outputIntervalHistogramback to summary
public synchronized void outputIntervalHistogram(final double startTimeStampSec, final double endTimeStampSec, final EncodableHistogram histogram, final double maxValueUnitRatio)

Output an interval histogram, with the given timestamp information and the [optional] tag associated with the histogram, using a configurable maxValueUnitRatio. (note that the specified timestamp information will be used, and the timestamp information in the actual histogram will be ignored). The max value reported with the interval line will be scaled by the given maxValueUnitRatio.

Parameters
startTimeStampSec:double

The start timestamp to log with the interval histogram, in seconds.

endTimeStampSec:double

The end timestamp to log with the interval histogram, in seconds.

histogram:EncodableHistogram

The interval histogram to log.

maxValueUnitRatio:double

The ratio by which to divide the histogram's max value when reporting on it.

outputIntervalHistogramback to summary
public void outputIntervalHistogram(final double startTimeStampSec, final double endTimeStampSec, final EncodableHistogram histogram)

Output an interval histogram, with the given timestamp information, and the [optional] tag associated with the histogram. (note that the specified timestamp information will be used, and the timestamp information 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:double

The start timestamp to log with the interval histogram, in seconds.

endTimeStampSec:double

The end timestamp to log with the interval histogram, in seconds.

histogram:EncodableHistogram

The interval histogram to log.

outputIntervalHistogramback to summary
public void outputIntervalHistogram(final EncodableHistogram histogram)

Output an interval histogram, using the start/end timestamp indicated in the histogram, and the [optional] tag associated with the histogram. The histogram start and end timestamps are assumed to be in msec units. Logging will be in seconds, realtive by a base time (if set via org.HdrHistogram.HistogramLogWriter#setBaseTime). The default base time is 0.

By covention, histogram start/end time are generally stamped with absolute times in msec since the epoch. For logging with absolute time stamps, the base time would remain zero. For logging with relative time stamps (time since a start point), the base time should be set with org.HdrHistogram.HistogramLogWriter#setBaseTime.

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 if some other ratio is needed for the max value output.

Parameters
histogram:EncodableHistogram

The interval histogram to log.

outputLegendback to summary
public void outputLegend()

Output a legend line to the log.

outputLogFormatVersionback to summary
public void outputLogFormatVersion()

Output a log format version to the log.

outputStartTimeback to summary
public void outputStartTime(final long startTimeMsec)

Log a start time in the log.

Parameters
startTimeMsec:long

time (in milliseconds) since the absolute start time (the epoch)

setBaseTimeback to summary
public void setBaseTime(long baseTimeMsec)

Set a base time to subtract from supplied histogram start/end timestamps when logging based on histogram timestamps. Base time is expected to be in msec since the epoch, as histogram start/end times are typically stamped with absolute times in msec since the epoch.

Parameters
baseTimeMsec:long

base time to calculate timestamp deltas from