Documentation ¶
Overview ¶
Package hdrhist provides high dynamic range (HDR) histograms.
HDR histograms can be used to accurately record and analyze distributions with very large ranges of data. This HDR histogram implementation is meant to have minimal memory usage and support recording values quickly. With a precision of 3 significant digits and a range of 1000-100 billion (e.g. 1 μs to 100 s), an HDR histogram consumes about 156 KB. Benchmarks show that recording a value in a histogram should take about 12 ns depending on the hardware.
A typical usecase for HDR Histograms would be recording latency values in client or server software.
This package is a Go port of Gil Tene's HdrHistogram Java package (http://hdrhistogram.github.io/HdrHistogram/). Package hdrhist aims to interoperate with HdrHistogram to the fullest extent possible.
Unless otherwise noted, none of the types in the package are safe for concurrent use.
Index ¶
- type Config
- type Hist
- func (h *Hist) Add(o *Hist)
- func (h *Hist) AllVals() []HistVal
- func (h *Hist) Clear()
- func (h *Hist) Clone() *Hist
- func (h *Hist) Config() Config
- func (h *Hist) EndTime() (time.Time, bool)
- func (h *Hist) EstMemSize() int
- func (h *Hist) Init(cfg Config)
- func (h *Hist) Max() int64
- func (h *Hist) Mean() float64
- func (h *Hist) Min() int64
- func (h *Hist) PercentileVal(p float64) HistVal
- func (h *Hist) Record(v int64)
- func (h *Hist) RecordCorrected(v int64, expectedInterval int64)
- func (h *Hist) RecordN(v, count int64)
- func (h *Hist) SetAutoResize(b bool)
- func (h *Hist) SetEndTime(t time.Time)
- func (h *Hist) SetStartTime(t time.Time)
- func (h *Hist) StartTime() (time.Time, bool)
- func (h *Hist) Stdev() float64
- func (h *Hist) Sub(o *Hist)
- func (h *Hist) TotalCount() int64
- func (h *Hist) Val(v int64) HistVal
- type HistVal
- type LogReader
- type LogWriter
- func (l *LogWriter) GetBaseTime() (time.Time, bool)
- func (l *LogWriter) SetBaseTime(base time.Time)
- func (l *LogWriter) WriteBaseTime(base time.Time) error
- func (l *LogWriter) WriteComment(text string) error
- func (l *LogWriter) WriteIntervalHist(h *Hist) error
- func (l *LogWriter) WriteLegend() error
- func (l *LogWriter) WriteStartTime(start time.Time) error
- type Recorder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct { // LowestDiscernible is the lowest, positive value // that can be discerned from 0. // This number may be rounded down to the nearest power of 2. LowestDiscernible int64 // HighestTrackable is the largest value // that can be tracked by the histogram. // This must be at least twice the value of LowestDiscernible. HighestTrackable int64 // SigFigs are the number of significant figures // that will be maintained by the histogram. // Must be ∈ [0,5]. SigFigs int32 // AutoResize will adjust HighestTrackable // and resize the histogram if necessary. // Note that resizing the histogram requires allocation // and will take longer than a typical operation. AutoResize bool // contains filtered or unexported fields }
Config contains the options that can be used to configure a Hist.
type Hist ¶
type Hist struct {
// contains filtered or unexported fields
}
Hist maintains a distribution of values with a predetermined level of precision. A Hist can distinguish values with a predetermined range, or optionally resize to handle large values as they are provided.
func New ¶
New creates a new Hist that auto-resizes and has a LowestDiscernible value of 1. Valid values for sigfigs are between 0 and 5.
func WithConfig ¶
WithConfig creates a new Hist with the provided Config.
func (*Hist) Clear ¶
func (h *Hist) Clear()
Clear deletes all recorded values as well as the start and end times.
func (*Hist) Clone ¶
Clone returns a deep copy of the histogram. This is useful when combining or taking differences of histograms.
func (*Hist) EstMemSize ¶
EstMemSize estimates the number of bytes being consumed by the histogram. The resulting size should not be assumed to be exact. The return value is in bytes.
func (*Hist) PercentileVal ¶
PercentileVal returns the HistVal at the requested percentile p. p should be in the range [0, 100].
func (*Hist) RecordCorrected ¶
func (*Hist) SetAutoResize ¶
func (*Hist) SetEndTime ¶
func (*Hist) SetStartTime ¶
func (*Hist) TotalCount ¶
type LogReader ¶
type LogReader struct {
// contains filtered or unexported fields
}
LogReader reads hists from a log file.
LogReader currently provides no mechanism for extracting comments, or start times.
func NewLogReader ¶
type LogWriter ¶
type LogWriter struct {
// contains filtered or unexported fields
}
A LogWriter writes Hist's to a log file.
· A log file may optionally have a start time. · A log file may optionally have a base time, which will be used to reduce the space consumption of timestamps. · A log file may have comments interleaved with histograms.
Typical usage of a LogWriter would be as follows:
now := time.Now() lw := NewLogWriter(w) lw.WriteStartTime(now) lw.SetBaseTime(now) lw.WriteLegend()
LogWriter is unfortunately difficult to use and was taken almost directly from the Java pacakge. This API should be revisited.
func NewLogWriter ¶
func (*LogWriter) SetBaseTime ¶
func (*LogWriter) WriteComment ¶
func (*LogWriter) WriteIntervalHist ¶
func (*LogWriter) WriteLegend ¶
type Recorder ¶
type Recorder struct {
// contains filtered or unexported fields
}
Recorder provides a recording-only convenience API for snapshotting Hists.