timeseries

package
v2.0.0-beta2.0...-114790f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 18, 2024 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package timeseries defines the interface for managing time seres objects and provides time range manipulation capabilities

Index

Constants

View Source 
const (
	// TimeRangeQueryCtx is a unique Context identifier for Time Range Query information
	TimeRangeQueryCtx timeSeriesCtxVal = iota
	// RequestOptionsCtx is a unique Context identifier for Request Options information
	RequestOptionsCtx
)
View Source 
const BackfillToleranceFlag = "trickster-backfill-tolerance:"

BackfillToleranceFlag is a string that is checked to determine if Backfill Tolerance should be adjusted for the provided query

View Source 
const FastForwardUserDisableFlag = "trickster-fast-forward:off"

FastForwardUserDisableFlag is a string that is checked to determine if Fast Forward should be selectively disabled for the provided query

View Source 
const Second = 1000000000

Second is 1B, because 1B Nanoseconds == 1 Second

Variables

View Source 
var ErrInvalidBody = errors.New("could not deserialize result body")

ErrInvalidBody is an error for when a provided body cannot be deserialized to a DataSet

View Source 
var ErrInvalidExtent = errors.New("invalid extent")

ErrInvalidExtent is an error for invalid extent (e.g., end is before start)

View Source 
var ErrInvalidTimeFormat = errors.New("invalid time format")

ErrInvalidTimeFormat is an error for when the provided time is not in the expected format

View Source 
var ErrNoTimerangeQuery = errors.New("no timerange query")

ErrNoTimerangeQuery is an error for when a method is provided a nil *TimeRangeQuery

View Source 
var ErrTableHeader = errors.New("could not deserialize table header")

ErrTableHeader is an error for could not deserialize table header

View Source 
var ErrUnknownFormat = errors.New("unknown timeseries format")

ErrUnknownFormat is an error for when a provided TimeSeries cannot be cast to a DataSet

View Source 
var ErrUnmarshalEpoch = errors.New("could not convert value to epoch timestamp")

ErrUnmarshalEpoch is an error for invalid epoch timestamp format

Functions

This section is empty.

Types

type Extent 

type Extent struct {
	Start    time.Time `msg:"start" json:"start"`
	End      time.Time `msg:"end" json:"end"`
	LastUsed time.Time `msg:"lu" json:"-"`
}

Extent describes the start and end times for a given range of data

func (*Extent) After 

func (e *Extent) After(t time.Time) bool

After returns true if the range of the Extent is completely after the provided time

func (*Extent) DecodeMsg 

func (z *Extent) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (Extent) EncodeMsg 

func (z Extent) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*Extent) EndsAt 

func (e *Extent) EndsAt(t time.Time) bool

EndsAt returns true if t is equal to the Extent's end time

func (*Extent) EndsAtOrAfter 

func (e *Extent) EndsAtOrAfter(t time.Time) bool

EndsAtOrAfter returns true if t is equal to or after the Extent's end time

func (*Extent) EndsAtOrBefore 

func (e *Extent) EndsAtOrBefore(t time.Time) bool

EndsAtOrBefore returns true if t is equal to or earlier than the Extent's end time

func (*Extent) Includes 

func (e *Extent) Includes(t time.Time) bool

Includes returns true if the Extent includes the provided Time

func (Extent) MarshalMsg 

func (z Extent) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (Extent) Msgsize 

func (z Extent) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Extent) StartsAt 

func (e *Extent) StartsAt(t time.Time) bool

StartsAt returns true if t is equal to the Extent's start time

func (*Extent) StartsAtOrAfter 

func (e *Extent) StartsAtOrAfter(t time.Time) bool

StartsAtOrAfter returns true if t is equal to or after the Extent's start time

func (*Extent) StartsAtOrBefore 

func (e *Extent) StartsAtOrBefore(t time.Time) bool

StartsAtOrBefore returns true if t is equal or before to the Extent's start time

func (Extent) String 

func (e Extent) String() string

String returns the string representation of the Extent

func (*Extent) UnmarshalMsg 

func (z *Extent) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type ExtentList 

type ExtentList []Extent

ExtentList is a type of []Extent used for sorting the slice

func (ExtentList) CalculateDeltas 

func (el ExtentList) CalculateDeltas(want Extent, step time.Duration) ExtentList

CalculateDeltas provides a list of extents that are not in a cached timeseries, when provided a list of extents that are cached.

func (ExtentList) Clone 

func (el ExtentList) Clone() ExtentList

Clone returns a true copy of the ExtentList

func (ExtentList) CloneRange 

func (el ExtentList) CloneRange(start, end int) ExtentList

CloneRange returns a perfect copy of the ExtentList, cloning only the Extents in the provided index range (upper-bound exclusive)

func (ExtentList) Compress 

func (el ExtentList) Compress(step time.Duration) ExtentList

Compress sorts an ExtentList and merges time-adjacent Extents so that the total extent of data is accurately represented in as few Extents as possible

func (ExtentList) Crop 

func (el ExtentList) Crop(e Extent) ExtentList

Crop reduces the ExtentList to the boundaries defined by the provided Extent

func (*ExtentList) DecodeMsg 

func (z *ExtentList) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (ExtentList) EncodeMsg 

func (z ExtentList) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (ExtentList) EncompassedBy 

func (el ExtentList) EncompassedBy(e Extent) bool

EncompassedBy returns true if the provided extent completely surrounds the boundaries of the subject ExtentList

func (ExtentList) Encompasses 

func (el ExtentList) Encompasses(e Extent) bool

Encompasses returns true if the provided extent is contained completely within boundaries of the subject ExtentList

func (ExtentList) Equal 

func (el ExtentList) Equal(el2 ExtentList) bool

Equal returns true if the provided extent list is identical to the subject list

func (ExtentList) Len 

func (el ExtentList) Len() int

Len returns the length of a slice of type ExtentList

func (ExtentList) Less 

func (el ExtentList) Less(i, j int) bool

Less returns true if element i in the ExtentList comes before j

func (ExtentList) MarshalMsg 

func (z ExtentList) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (ExtentList) Msgsize 

func (z ExtentList) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (ExtentList) OutsideOf 

func (el ExtentList) OutsideOf(e Extent) bool

OutsideOf returns true if the provided extent falls completely outside of the boundaries of the subject extent list

func (ExtentList) Remove 

func (el ExtentList) Remove(r ExtentList, step time.Duration) ExtentList

Remove removes the provided extent list ranges from the subject extent list

func (ExtentList) Size 

func (el ExtentList) Size() int

Size returns the approximate memory utilization in bytes of the timeseries

func (ExtentList) Splice 

func (el ExtentList) Splice(step, maxRange, spliceStep time.Duration, maxPoints int) ExtentList

Splice breaks apart extents in the list into smaller, contiguous extents, based on the provided splice sizing options, and returns the resulting spliced list. Splice assumes el is Compressed (e.g., Compress() was just ran or would be innefectual if ran)

func (ExtentList) String 

func (el ExtentList) String() string

String returns a string representation of the extentlist in the format startEpochSec1-endEpochSec1;startEpochSec2-endEpochSec2

func (ExtentList) Swap 

func (el ExtentList) Swap(i, j int)

Swap modifies an ExtentList by swapping the values in indexes i and j

func (ExtentList) TimestampCount 

func (el ExtentList) TimestampCount(d time.Duration) int64

TimestampCount returns the calculated number of timestamps based on the extents in the list and the provided duration

func (*ExtentList) UnmarshalMsg 

func (z *ExtentList) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type ExtentListLRU 

type ExtentListLRU []Extent

ExtentListLRU is a type of []Extent used for sorting the slice by LRU

func (ExtentListLRU) Clone 

func (el ExtentListLRU) Clone() ExtentListLRU

Clone returns a true copy of the ExtentListLRU

func (*ExtentListLRU) DecodeMsg 

func (z *ExtentListLRU) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (ExtentListLRU) EncodeMsg 

func (z ExtentListLRU) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (ExtentListLRU) Len 

func (el ExtentListLRU) Len() int

Len returns the length of an slice of type ExtentListLRU

func (ExtentListLRU) Less 

func (el ExtentListLRU) Less(i, j int) bool

Less returns true if element i in the ExtentListLRU comes before j

func (ExtentListLRU) MarshalMsg 

func (z ExtentListLRU) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (ExtentListLRU) Msgsize 

func (z ExtentListLRU) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (ExtentListLRU) String 

func (el ExtentListLRU) String() string

func (ExtentListLRU) Swap 

func (el ExtentListLRU) Swap(i, j int)

Swap modifies an ExtentListLRU by swapping the values in indexes i and j

func (*ExtentListLRU) UnmarshalMsg 

func (z *ExtentListLRU) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

func (ExtentListLRU) UpdateLastUsed 

func (el ExtentListLRU) UpdateLastUsed(lur Extent, step time.Duration) ExtentListLRU

UpdateLastUsed updates the ExtentListLRU's LastUsed field for the provided extent. The step is required in order to properly split extents.

type FieldDataType 

type FieldDataType byte

FieldDataType is a byte representing the data type of a Field when stored in a Point's Values list 

const (
	Unknown FieldDataType = iota
	Int64
	Float64
	String
	Bool
	Byte
	Int16
)

Field Data Types

func (*FieldDataType) DecodeMsg 

func (z *FieldDataType) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (FieldDataType) EncodeMsg 

func (z FieldDataType) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (FieldDataType) MarshalMsg 

func (z FieldDataType) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (FieldDataType) Msgsize 

func (z FieldDataType) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*FieldDataType) UnmarshalMsg 

func (z *FieldDataType) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type FieldDefinition 

type FieldDefinition struct {
	Name           string        `msg:"name"`
	DataType       FieldDataType `msg:"type"`
	OutputPosition int           `msg:"pos"`
	SDataType      string        `msg:"stype"`
	ProviderData1  int           `msg:"provider1"`
}

FieldDefinition describes a field by name and type

func (FieldDefinition) Clone 

func (fd FieldDefinition) Clone() FieldDefinition

Clone returns a perfect, new copy of the FieldDefinition

func (*FieldDefinition) DecodeMsg 

func (z *FieldDefinition) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*FieldDefinition) EncodeMsg 

func (z *FieldDefinition) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*FieldDefinition) MarshalMsg 

func (z *FieldDefinition) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*FieldDefinition) Msgsize 

func (z *FieldDefinition) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (FieldDefinition) Size 

func (fd FieldDefinition) Size() int

Size returns the size of the FieldDefintions in bytes

func (FieldDefinition) String 

func (fd FieldDefinition) String() string

func (*FieldDefinition) UnmarshalMsg 

func (z *FieldDefinition) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type FieldDefinitions 

type FieldDefinitions []FieldDefinition

FieldDefinitions represents a list type FieldDefinition

func (*FieldDefinitions) DecodeMsg 

func (z *FieldDefinitions) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (FieldDefinitions) EncodeMsg 

func (z FieldDefinitions) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (FieldDefinitions) MarshalMsg 

func (z FieldDefinitions) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (FieldDefinitions) Msgsize 

func (z FieldDefinitions) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (FieldDefinitions) String 

func (fds FieldDefinitions) String() string

func (*FieldDefinitions) UnmarshalMsg 

func (z *FieldDefinitions) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type MarshalWriterFunc 

type MarshalWriterFunc func(Timeseries, *RequestOptions, int, io.Writer) error

MarshalWriterFunc describes a function that marshals a Timeseries to an io.Writer

type MarshalerFunc 

type MarshalerFunc func(Timeseries, *RequestOptions, int) ([]byte, error)

MarshalerFunc describes a function that marshals a Timeseries

type Modeler 

type Modeler struct {
	WireUnmarshalerReader UnmarshalerReaderFunc `msg:"-"`
	WireUnmarshaler       UnmarshalerFunc       `msg:"-"`
	WireMarshaler         MarshalerFunc         `msg:"-"`
	WireMarshalWriter     MarshalWriterFunc     `msg:"-"`
	CacheUnmarshaler      UnmarshalerFunc       `msg:"-"`
	CacheMarshaler        MarshalerFunc         `msg:"-"`
}

Modeler is a container object for Timeseries marshaling operations

func NewModeler 

func NewModeler(
	wu UnmarshalerFunc, wur UnmarshalerReaderFunc,
	wm MarshalerFunc, wmw MarshalWriterFunc,
	cu UnmarshalerFunc, cm MarshalerFunc) *Modeler

NewModeler factories a modeler with the provided modeling functions

func (*Modeler) DecodeMsg 

func (z *Modeler) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (Modeler) EncodeMsg 

func (z Modeler) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (Modeler) MarshalMsg 

func (z Modeler) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (Modeler) Msgsize 

func (z Modeler) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*Modeler) UnmarshalMsg 

func (z *Modeler) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type RequestOptions 

type RequestOptions struct {
	// TimeFormat is a field usable by time series implementations to pass data between the parsed time range query
	// and the data unmarshaler/marshaler to give indications about the format of Timestamps in the serialized dataset
	TimeFormat byte
	// OutputFormat is a field usable by time series implementations to pass data between the parsed time range query
	// and the data unmarshaler/marshaler to give indications about the content type of the serialized output
	OutputFormat byte
	// FastForwardDisable indicates whether the Time Range Query result should include fast forward data
	FastForwardDisable bool
	// BaseTimestampFieldName holds the name of the Base Timestamp Field (in case it is aliased with AS) to help
	// parse WHERE clauses during the initial parsing of a query
	BaseTimestampFieldName string
}

RequestOptions holds request-specific information about a query

func (*RequestOptions) ExtractFastForwardDisabled 

func (ro *RequestOptions) ExtractFastForwardDisabled(input string)

ExtractFastForwardDisabled will look for the FastForwardUserDisableFlag in the provided string and set the flag appropriately in the subject RequestOptions

type TimeRangeQuery 

type TimeRangeQuery struct {
	// Statement is the timeseries database query (with tokenized timeranges where present) requested by the user
	Statement string `msg:"stmt"`
	// Extent provides the start and end times for the request from a timeseries database
	Extent Extent `msg:"ex"`
	// Step indicates the amount of time in seconds between each datapoint in a TimeRangeQuery's resulting timeseries
	Step time.Duration `msg:"-"`
	// TemplateURL is used by some Backend providers for templatization of url parameters containing timestamps
	TemplateURL *url.URL `msg:"-"`
	// IsOffset is true if the query uses a relative offset modifier
	IsOffset bool `msg:"-"`
	// StepNS is the nanosecond representation for Step
	StepNS int64 `msg:"step"`
	// BackfillTolerance can be updated to override the overall backfill tolerance per query
	BackfillTolerance time.Duration `msg:"-"`
	// BackfillToleranceNS is the nanosecond representation for BackfillTolerance
	BackfillToleranceNS int64 `msg:"bft"`
	// RecordLimit is the LIMIT value of the query
	RecordLimit int `msg:"rl"`
	// TimestampDefinition sets the definition for the Timestamp column in the in the timeseries based on the query
	TimestampDefinition FieldDefinition `msg:"tsdef"`
	// TagFieldDefinitions contains the definitions for Tag columns in the timeseries, based on the query
	TagFieldDefintions []FieldDefinition `msg:"tfdefs"`
	// ValueFieldDefinitions contains the definitions for Value columns in the timeseries, based on the query
	ValueFieldDefinitions []FieldDefinition `msg:"vfdefs"`
	// ParsedQuery is a member for the vendor-specific query object
	ParsedQuery interface{} `msg:"-"`
}

TimeRangeQuery represents a timeseries database query parsed from an inbound HTTP request

func (*TimeRangeQuery) Clone 

func (trq *TimeRangeQuery) Clone() *TimeRangeQuery

Clone returns an exact copy of a TimeRangeQuery

func (*TimeRangeQuery) DecodeMsg 

func (z *TimeRangeQuery) DecodeMsg(dc *msgp.Reader) (err error)

DecodeMsg implements msgp.Decodable

func (*TimeRangeQuery) EncodeMsg 

func (z *TimeRangeQuery) EncodeMsg(en *msgp.Writer) (err error)

EncodeMsg implements msgp.Encodable

func (*TimeRangeQuery) ExtractBackfillTolerance 

func (trq *TimeRangeQuery) ExtractBackfillTolerance(input string)

ExtractBackfillTolerance will look for the BackfillToleranceFlag in the provided string and return the BackfillTolerance value if present

func (*TimeRangeQuery) GetBackfillTolerance 

func (trq *TimeRangeQuery) GetBackfillTolerance(def time.Duration, points int) time.Duration

GetBackfillTolerance will return the backfill tolerance for the query based on the provided defaults, and any query-specific tolerance directives included in the query comments

func (*TimeRangeQuery) MarshalMsg 

func (z *TimeRangeQuery) MarshalMsg(b []byte) (o []byte, err error)

MarshalMsg implements msgp.Marshaler

func (*TimeRangeQuery) Msgsize 

func (z *TimeRangeQuery) Msgsize() (s int)

Msgsize returns an upper bound estimate of the number of bytes occupied by the serialized message

func (*TimeRangeQuery) NormalizeExtent 

func (trq *TimeRangeQuery) NormalizeExtent()

NormalizeExtent adjusts the Start and End of a TimeRangeQuery's Extent to align against normalized boundaries.

func (*TimeRangeQuery) Size 

func (trq *TimeRangeQuery) Size() int

Size returns the memory usage in bytes of the TimeRangeQuery

func (*TimeRangeQuery) String 

func (trq *TimeRangeQuery) String() string

func (*TimeRangeQuery) UnmarshalMsg 

func (z *TimeRangeQuery) UnmarshalMsg(bts []byte) (o []byte, err error)

UnmarshalMsg implements msgp.Unmarshaler

type Timeseries 

type Timeseries interface {
	// SetExtents sets the Extents of the Timeseries
	SetExtents(ExtentList)
	// Extents should return the list of time Extents having data present in the Timeseries
	Extents() ExtentList
	// VolatileExtents should return the list of time Extents in the cached Timeseries
	// that should be re-fetched
	VolatileExtents() ExtentList
	// SetVolatileExtents sets the list of time Extents in the cached Timeseries
	// that should be re-fetched
	SetVolatileExtents(ExtentList)
	// TimeStampCount should return the number of unique timestamps across the timeseries
	TimestampCount() int64
	// Step should return the Step Interval of the Timeseries
	Step() time.Duration
	// Merge should merge the Timeseries collection into the source Timeseries
	Merge(bool, ...Timeseries)
	// Sort should uniqueify and sort all series by Timestamp
	Sort()
	// Clone should return an exact duplicate source the Timeseries
	Clone() Timeseries
	// CroppedClone should return an exact duplicate source the Timeseries, excluding any
	// timestamps from the source Timeseries that fall outside of the provided extent
	CroppedClone(Extent) Timeseries
	// CropToRange should reduce time range of the Timeseries to the provided Extent
	CropToRange(Extent)
	// CropToSize should reduce time range of the Timeseries to the provided element size using
	// a least-recently-used methodology, while limiting the upper extent to the provided time,
	// in order to support backfill tolerance
	CropToSize(int, time.Time, Extent)
	// SeriesCount returns the number of individual Series in the Timeseries object
	SeriesCount() int
	// ValueCount returns the count of all values across all Series in the Timeseries object
	ValueCount() int64
	// Size returns the approximate memory byte size of the timeseries object
	Size() int64
	// SetTimeRangeQuery sets the TimeRangeQuery associated with the Timeseries
	SetTimeRangeQuery(*TimeRangeQuery)
}

Timeseries represents a Response Object from a Timeseries Database

type UnmarshalerFunc 

type UnmarshalerFunc func([]byte, *TimeRangeQuery) (Timeseries, error)

UnmarshalerFunc describes a function that unmarshals a Timeseries

type UnmarshalerReaderFunc 

type UnmarshalerReaderFunc func(io.Reader, *TimeRangeQuery) (Timeseries, error)

UnmarshalerReaderFunc describes a function that unmarshals a Timeseries from an io.Reader

Source Files

View all Source files

Directories

Path Synopsis
Package dataset defines the interface for managing time seres objects and provides time range manipulation capabilities
 Package dataset defines the interface for managing time seres objects and provides time range manipulation capabilities
Package sqlparser provides customizations to the base sql parser that are specific to timeseries (for example, parsing trickster directives from comments)
 Package sqlparser provides customizations to the base sql parser that are specific to timeseries (for example, parsing trickster directives from comments)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.