whisper-go: github.com/kisielk/whisper-go/whisper Index | Files

package whisper

import "github.com/kisielk/whisper-go/whisper"

Package whisper implements an interface to the whisper database format used by the Graphite project (https://github.com/graphite-project/)


Package Files

util.go whisper.go


const (
    DefaultXFilesFactor      = 0.5
    DefaultAggregationMethod = AggregationAverage


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

type AggregationMethod Uses

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 Uses

func (m AggregationMethod) String() (s string)

type ArchiveInfo Uses

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 Uses

func NewArchiveInfo(secondsPerPoint, points uint32) ArchiveInfo

NewArchiveInfo returns a new ArchiveInfo with a zero offset.

func ParseArchiveInfo Uses

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 Uses

func (a ArchiveInfo) Retention() uint32

Retention is the retention period of the archive in seconds.

func (ArchiveInfo) Size Uses

func (a ArchiveInfo) Size() uint32

Size is the size of the archive in bytes.

type CreateOptions Uses

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 Uses

func DefaultCreateOptions() CreateOptions
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 Uses

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.

func (Interval) Duration Uses

func (i Interval) Duration() time.Duration

Duration returns the interval length as a time.Duration

func (Interval) From Uses

func (i Interval) From() time.Time

From returns the interval's FromTimestamp as a time.Time

func (Interval) Until Uses

func (i Interval) Until() time.Time

Until returns the interval's UntilTimestamp as a time.Time

type Metadata Uses

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 Uses

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.

func NewPoint Uses

func NewPoint(t time.Time, v float64) Point

NewPoint constructs a new Point at time t with value v.

func (Point) Time Uses

func (p Point) Time() time.Time

Time returns the time for the Point p

type Whisper Uses

type Whisper struct {
    Header Header
    // contains filtered or unexported fields

Whisper represents a handle to a whisper database.

func Create Uses

func Create(path string, archives []ArchiveInfo, options CreateOptions) (*Whisper, error)

Create attempts to create a new database at the given filepath.

func Open Uses

func Open(path string) (*Whisper, error)

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 Uses

func OpenWhisper(f io.ReadWriteSeeker) (*Whisper, error)

OpenWhisper opens an existing Whisper database from the given ReadWriteSeeker.

func (*Whisper) Close Uses

func (w *Whisper) Close() error

Close closes a whisper database.

func (*Whisper) DumpArchive Uses

func (w *Whisper) DumpArchive(n int) ([]Point, error)

func (*Whisper) Fetch Uses

func (w *Whisper) Fetch(from uint32) (Interval, []Point, error)

Fetch is equivalent to calling FetchUntil with until set to time.Now()

func (*Whisper) FetchTime Uses

func (w *Whisper) FetchTime(from time.Time) (Interval, []Point, error)

FetchTime is like Fetch but accepts a time.Time

func (*Whisper) FetchUntil Uses

func (w *Whisper) FetchUntil(from, until uint32) (interval Interval, points []Point, err error)

FetchUntil returns all points between two timestamps

func (*Whisper) FetchUntilTime Uses

func (w *Whisper) FetchUntilTime(from, until time.Time) (Interval, []Point, error)

FetchUntilTime is like FetchUntil but accepts time.Time

func (*Whisper) SetAggregationMethod Uses

func (w *Whisper) SetAggregationMethod(m AggregationMethod) error

SetAggregationMethod updates the aggregation method for the database

func (*Whisper) Update Uses

func (w *Whisper) Update(point Point) error

Update writes a single datapoint to the whisper database

func (*Whisper) UpdateMany Uses

func (w *Whisper) UpdateMany(points []Point) error

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.

Package whisper imports 10 packages (graph) and is imported by 6 packages. Updated 2019-02-08. Refresh now. Tools for package owners.