Documentation
¶
Overview ¶
Package whisper implements an interface to the whisper database format used by the Graphite project (https://github.com/graphite-project/)
Index ¶
- Constants
- Variables
- type AggregationMethod
- type ArchiveInfo
- type CreateOptions
- type Header
- type Interval
- type Metadata
- type Point
- type Whisper
- func (w *Whisper) Close() error
- func (w *Whisper) DumpArchive(n int) ([]Point, error)
- func (w *Whisper) Fetch(from uint32) (Interval, []Point, error)
- func (w *Whisper) FetchTime(from time.Time) (Interval, []Point, error)
- func (w *Whisper) FetchUntil(from, until uint32) (interval Interval, points []Point, err error)
- func (w *Whisper) FetchUntilTime(from, until time.Time) (Interval, []Point, error)
- func (w *Whisper) SetAggregationMethod(m AggregationMethod) error
- func (w *Whisper) Update(point Point) error
- func (w *Whisper) UpdateMany(points []Point) error
Constants ¶
const ( DefaultXFilesFactor = 0.5 DefaultAggregationMethod = AggregationAverage )
Variables ¶
var ( ErrNoArchives = errors.New("archive list must contain at least one archive.") ErrDuplicateArchive = errors.New("no archive may be a duplicate of another.") ErrUnevenPrecision = errors.New("higher precision archives must evenly divide in to lower precision.") ErrLowRetention = errors.New("lower precision archives must cover a larger time interval than higher precision.") ErrInsufficientPoints = errors.New("archive has insufficient points to aggregate to a lower precision") )
Functions ¶
This section is empty.
Types ¶
type AggregationMethod ¶
type AggregationMethod uint32
The AggregationMethod type describes how values are aggregated from one Whisper archive to another.
const ( AggregationUnknown AggregationMethod = 0 // Unknown aggregation method AggregationAverage AggregationMethod = 1 // Aggregate using averaging AggregationSum AggregationMethod = 2 // Aggregate using sum AggregationLast AggregationMethod = 3 // Aggregate using the last value AggregationMax AggregationMethod = 4 // Aggregate using the maximum value AggregationMin AggregationMethod = 5 // Aggregate using the minimum value )
Valid aggregation methods
func (AggregationMethod) String ¶
func (m AggregationMethod) String() (s string)
type ArchiveInfo ¶
type ArchiveInfo struct {
Offset uint32 // The byte offset of the archive within the database
SecondsPerPoint uint32 // The number of seconds of elapsed time represented by a data point
Points uint32 // The number of data points
}
ArchiveInfo holds metadata about a single archive within a whisper database
func NewArchiveInfo ¶
func NewArchiveInfo(secondsPerPoint, points uint32) ArchiveInfo
NewArchiveInfo returns a new ArchiveInfo with a zero offset.
func ParseArchiveInfo ¶
func ParseArchiveInfo(archiveString string) (ArchiveInfo, error)
ParseArchiveInfo returns an ArchiveInfo represented by the string.
The string must consist of two numbers, the precision and retention, separated by a colon (:).
Both the precision and retention strings accept a unit suffix. Acceptable suffixes are: "s" for second, "m" for minute, "h" for hour, "d" for day, "w" for week, and "y" for year.
The precision string specifies how large of a time interval is represented by a single point in the archive.
The retention string specifies how long points are kept in the archive. If no suffix is given for the retention it is taken to mean a number of points and not a duration.
func (ArchiveInfo) Retention ¶
func (a ArchiveInfo) Retention() uint32
Retention is the retention period of the archive in seconds.
func (ArchiveInfo) Size ¶
func (a ArchiveInfo) Size() uint32
Size is the size of the archive in bytes.
type CreateOptions ¶
type CreateOptions struct {
// The XFiles factor to use. DefaultXFilesFactor if not set.
XFilesFactor float32
// The archive aggregation method to use. DefaultAggregationMethod if not set.
AggregationMethod AggregationMethod
// If true, allocate a sparse archive.
Sparse bool
}
CreateOptions sets the options used to create a new archive.
func DefaultCreateOptions ¶
func DefaultCreateOptions() CreateOptions
type Header ¶
type Header struct {
Metadata Metadata // General metadata about the database
Archives []ArchiveInfo // Information about each of the archives in the database, in order of precision
}
Header contains all the metadata about a whisper database.
type Interval ¶
type Interval struct {
FromTimestamp uint32 // Start of the interval in seconds since the epoch
UntilTimestamp uint32 // End of the interval in seconds since the epoch
Step uint32 // Step size in seconds
}
Interval repsents a time interval with a step.
type Metadata ¶
type Metadata struct {
// Aggregation method used. See the Aggregation* constants.
AggregationMethod AggregationMethod
// The maximum retention period.
MaxRetention uint32
// The minimum percentage of known values required to aggregate.
XFilesFactor float32
// The number of archives in the database.
ArchiveCount uint32
}
Metadata holds metadata that's common to an entire whisper database
type Point ¶
type Point struct {
Timestamp uint32 // Timestamp in seconds past the epoch
Value float64 // Data point value
}
Point is a single datum stored in a whisper database.
type Whisper ¶
type Whisper struct {
Header Header
// contains filtered or unexported fields
}
Whisper represents a handle to a whisper database.
func Create ¶
func Create(path string, archives []ArchiveInfo, options CreateOptions) (*Whisper, error)
Create attempts to create a new database at the given filepath.
func Open ¶
Open opens an existing whisper database. It returns an error if the file does not exist or is not a valid whisper archive.
func OpenWhisper ¶
func OpenWhisper(f io.ReadWriteSeeker) (*Whisper, error)
OpenWhisper opens an existing Whisper database from the given ReadWriteSeeker.
func (*Whisper) FetchUntil ¶
FetchUntil returns all points between two timestamps
func (*Whisper) FetchUntilTime ¶
FetchUntilTime is like FetchUntil but accepts time.Time
func (*Whisper) SetAggregationMethod ¶
func (w *Whisper) SetAggregationMethod(m AggregationMethod) error
SetAggregationMethod updates the aggregation method for the database
func (*Whisper) UpdateMany ¶
UpdateMany write a slice of datapoints to the whisper database. The points do not have to be unique or sorted. If two points cover the same time interval the last point encountered will be retained.
Source Files