v0.0.0-...-e25bc3e Latest Latest

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

Go to latest
Published: May 13, 2021 License: MIT Imports: 19 Imported by: 63



Package opentsdb defines structures for interacting with an OpenTSDB server.



View Source
const (
	Millisecond Duration = Duration(time.Millisecond)
	Second               = 1000 * Millisecond
	Minute               = 60 * Second
	Hour                 = 60 * Minute
	Day                  = Hour * 24
	Week                 = Day * 7
	Month                = Day * 30
	Year                 = Day * 365
View Source
const TSDBTimeFormat = "2006/01/02-15:04:05"

TSDBTimeFormat is the OpenTSDB-required time format for the time package.


View Source
var DefaultClient = &http.Client{
	Timeout: time.Minute,

DefaultClient is the default http client for requests.

View Source
var Version2_1 = Version{2, 1}

OpenTSDB 2.1 version struct

View Source
var Version2_2 = Version{2, 2}

OpenTSDB 2.2 version struct


func CanonicalTime

func CanonicalTime(v interface{}) (string, error)

CanonicalTime converts v to a string for use with OpenTSDB's `/` route.

func Clean

func Clean(s string) (string, error)

Clean is Replace with an empty replacement string.

func FilterTags

func FilterTags(r *Request, tr ResponseSet)

FilterTags removes tagks in tr not present in r. Does nothing in the event of multiple queries in the request.

func MustReplace

func MustReplace(s, replacement string) string

MustReplace is like Replace, but returns an empty string on error.

func NewOpenTsdbNameProcessor

func NewOpenTsdbNameProcessor(invalidRuneReplacement string) (name.RuneLevelProcessor, error)

NewOpenTsdbNameProcessor constructs a new name.RuneLevelProcessor which can work with the OpenTSDB name format

func ParseAbsTime

func ParseAbsTime(s string) (time.Time, error)

ParseAbsTime returns the time of s, which must be of any non-relative (not "X-ago") format supported by OpenTSDB.

func ParseTime

func ParseTime(v interface{}) (time.Time, error)

ParseTime returns the time of v, which can be of any format supported by OpenTSDB.

func Replace

func Replace(s, replacement string) (string, error)

Replace removes characters from s that are invalid for OpenTSDB metric and tag values and replaces them. See:

func ReplaceTags

func ReplaceTags(text string, group TagSet) string

ReplaceTags replaces all tag-like strings with tags from the given group. For example, given the string "test.metric{host=*}" and a TagSet with, this returns "test.metric{}".

func TryParseAbsTime

func TryParseAbsTime(v interface{}) interface{}

TryParseAbsTime attempts to parse v as an absolute time. It may be a string in the format of TSDBTimeFormat or a float64 of seconds since epoch. If so, the epoch as an int64 is returned. Otherwise, v is returned.

func ValidTSDBString

func ValidTSDBString(s string) bool

ValidTSDBString returns true if s is a valid metric or tag.


type Context

type Context interface {
	Query(*Request) (ResponseSet, error)
	Version() Version

Context is the interface for querying an OpenTSDB server.

type DataPoint

type DataPoint struct {
	Metric    string      `json:"metric"`
	Timestamp int64       `json:"timestamp"`
	Value     interface{} `json:"value"`
	Tags      TagSet      `json:"tags"`

DataPoint is a data point for the /api/put route:

func (*DataPoint) Clean

func (d *DataPoint) Clean() error

func (*DataPoint) MarshalJSON

func (d *DataPoint) MarshalJSON() ([]byte, error)

MarshalJSON verifies d is valid and converts it to JSON.

func (*DataPoint) Valid

func (d *DataPoint) Valid() bool

Valid returns whether d contains valid data (populated fields, valid tags) for submission to OpenTSDB.

type Duration

type Duration time.Duration

Duration extends time.Duration to support OpenTSDB time-format specifiers:

func GetDuration

func GetDuration(r *Request) (Duration, error)

GetDuration returns the duration from the request's start to end.

func ParseDuration

func ParseDuration(s string) (Duration, error)

ParseDuration is equivalent to time.ParseDuration, but supports time units specified at

func (Duration) HumanString

func (d Duration) HumanString() string

func (Duration) Seconds

func (d Duration) Seconds() float64

Seconds returns the duration as a floating point number of seconds.

func (Duration) String

func (d Duration) String() string

func (*Duration) UnmarshalText

func (d *Duration) UnmarshalText(text []byte) error

type Filter

type Filter struct {
	Type    string `json:"type"`
	TagK    string `json:"tagk"`
	Filter  string `json:"filter"`
	GroupBy bool   `json:"groupBy"`

func ParseFilters

func ParseFilters(rawFilters string, grouping bool, q *Query) ([]Filter, error)

ParseFilters parses filters in the form of `tagk=filterFunc(...),...` It also mimics OpenTSDB's promotion of queries with a * or no function to iwildcard and literal_or respectively

func (Filter) String

func (f Filter) String() string

type Filters

type Filters []Filter

func (Filters) String

func (filters Filters) String() string

type Host

type Host string

Host is a simple OpenTSDB Context with no additional features.

func (Host) Query

func (h Host) Query(r *Request) (ResponseSet, error)

Query performs the request to the OpenTSDB server.

type LimitContext

type LimitContext struct {
	Host string
	// Limit limits response size in bytes
	Limit int64
	// FilterTags removes tagks from results if that tagk was not in the request
	FilterTags bool
	// Use the version to see if groupby and filters are supported
	TSDBVersion Version

LimitContext is a context that enables limiting response size and filtering tags

func NewLimitContext

func NewLimitContext(host string, limit int64, version Version) *LimitContext

NewLimitContext returns a new context for the given host with response sizes limited to limit bytes.

func (*LimitContext) Query

func (c *LimitContext) Query(r *Request) (tr ResponseSet, err error)

Query returns the result of the request. r may be cached. The request is byte-limited and filtered by c's properties.

func (*LimitContext) Version

func (c *LimitContext) Version() Version

type MultiDataPoint

type MultiDataPoint []*DataPoint

MultiDataPoint holds multiple DataPoints:

type Point

type Point float64

Point is the Response data point type.

type Query

type Query struct {
	Aggregator  string      `json:"aggregator"`
	Metric      string      `json:"metric"`
	Rate        bool        `json:"rate,omitempty"`
	RateOptions RateOptions `json:"rateOptions,omitempty"`
	Downsample  string      `json:"downsample,omitempty"`
	Tags        TagSet      `json:"tags,omitempty"`
	Filters     Filters     `json:"filters,omitempty"`
	GroupByTags TagSet      `json:"-"`

Query is a query for a request:

func ParseQuery

func ParseQuery(query string, version Version) (q *Query, err error)

ParseQuery parses OpenTSDB queries of the form: avg:rate:cpu{k=v}. Validation errors will be returned along with a valid Query.

func (Query) String

func (q Query) String() string

type RateOptions

type RateOptions struct {
	Counter    bool  `json:"counter,omitempty"`
	CounterMax int64 `json:"counterMax,omitempty"`
	ResetValue int64 `json:"resetValue,omitempty"`
	DropResets bool  `json:"dropResets,omitempty"`

RateOptions are rate options for a query.

type Request

type Request struct {
	Start             interface{} `json:"start"`
	End               interface{} `json:"end,omitempty"`
	Queries           []*Query    `json:"queries"`
	NoAnnotations     bool        `json:"noAnnotations,omitempty"`
	GlobalAnnotations bool        `json:"globalAnnotations,omitempty"`
	MsResolution      bool        `json:"msResolution,omitempty"`
	ShowTSUIDs        bool        `json:"showTSUIDs,omitempty"`
	Delete            bool        `json:"delete,omitempty"`

Request holds query objects:

func ParseRequest

func ParseRequest(req string, version Version) (*Request, error)

ParseRequest parses OpenTSDB requests of the form: start=1h-ago&m=avg:cpu.

func RequestFromJSON

func RequestFromJSON(b []byte) (*Request, error)

RequestFromJSON creates a new request from JSON.

func (*Request) AutoDownsample

func (r *Request) AutoDownsample(l int) error

AutoDownsample sets the avg downsample aggregator to produce l points.

func (*Request) Query

func (r *Request) Query(host string) (ResponseSet, error)

Query performs a v2 OpenTSDB request to the given host. host should be of the form hostname:port. Uses DefaultClient. Can return a RequestError.

func (*Request) QueryResponse

func (r *Request) QueryResponse(host string, client *http.Client) (*http.Response, error)

QueryResponse performs a v2 OpenTSDB request to the given host. host should be of the form hostname:port. A nil client uses DefaultClient.

func (*Request) Search

func (r *Request) Search() string

Search returns a string suitable for OpenTSDB's `/` route.

func (*Request) SetTime

func (r *Request) SetTime(t time.Time) error

SetTime adjusts the start and end time of the request to assume t is now. Relative times ("1m-ago") are changed to absolute times. Existing absolute times are adjusted by the difference between time.Now() and t.

func (*Request) String

func (r *Request) String() string

type RequestError

type RequestError struct {
	Request string
	Err     struct {
		Code    int    `json:"code"`
		Message string `json:"message"`
		Details string `json:"details"`
	} `json:"error"`

RequestError is the error structure for request errors.

func (*RequestError) Error

func (r *RequestError) Error() string

type Response

type Response struct {
	Metric        string           `json:"metric"`
	Tags          TagSet           `json:"tags"`
	AggregateTags []string         `json:"aggregateTags"`
	DPS           map[string]Point `json:"dps"`

	// fields added by translating proxy
	SQL string `json:"sql,omitempty"`

Response is a query response:

func (*Response) Copy

func (r *Response) Copy() *Response

type ResponseSet

type ResponseSet []*Response

ResponseSet is a Multi-Set Response:

func (ResponseSet) Copy

func (r ResponseSet) Copy() ResponseSet

type TagSet

type TagSet map[string]string

TagSet is a helper class for tags.

func ParseTags

func ParseTags(t string) (TagSet, error)

ParseTags parses OpenTSDB tagk=tagv pairs of the form: k=v,m=o. Validation errors do not stop processing, and will return a non-nil TagSet.

func (TagSet) AllSubsets

func (t TagSet) AllSubsets() []string

func (TagSet) Clean

func (t TagSet) Clean() error

Clean removes characters from t that are invalid for OpenTSDB metric and tag values. An error is returned if a resulting tag is empty.

func (TagSet) Compatible

func (t TagSet) Compatible(o TagSet) bool

Compatible returns true if all keys that are in both o and t, have the same value.

func (TagSet) Copy

func (t TagSet) Copy() TagSet

Copy creates a new TagSet from t.

func (TagSet) Equal

func (t TagSet) Equal(o TagSet) bool

Equal returns true if t and o contain only the same k=v pairs.

func (TagSet) Intersection

func (t TagSet) Intersection(o TagSet) TagSet

Intersection returns the intersection of t and o.

func (TagSet) Merge

func (t TagSet) Merge(o TagSet) TagSet

Merge adds or overwrites everything from o into t and returns t.

func (TagSet) Overlaps

func (a TagSet) Overlaps(b TagSet) bool

Returns true if the two tagsets "overlap". Two tagsets overlap if they: 1. Have at least one key/value pair that matches 2. Have no keys in common where the values do not match

func (TagSet) String

func (t TagSet) String() string

String converts t to an OpenTSDB-style {a=b,c=b} string, alphabetized by key.

func (TagSet) Subset

func (t TagSet) Subset(o TagSet) bool

Subset returns true if all k=v pairs in o are in t.

func (TagSet) Tags

func (t TagSet) Tags() string

Tags is identical to String() but without { and }.

func (TagSet) Valid

func (t TagSet) Valid() bool

Valid returns whether t contains OpenTSDB-submittable tags.

type Version

type Version struct {
	Major int64
	Minor int64

func (Version) FilterSupport

func (v Version) FilterSupport() bool

func (*Version) UnmarshalText

func (v *Version) UnmarshalText(text []byte) error

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL