Index | Files

package opentsdb

import ""

Package opentsdb defines structures for interacting with an OpenTSDB server.


Package Files

duration.go tsdb.go


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
const TSDBTimeFormat = "2006/01/02-15:04:05"

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


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

DefaultClient is the default http client for requests.

var Version2_1 = Version{2, 1}

OpenTSDB 2.1 version struct

var Version2_2 = Version{2, 2}

OpenTSDB 2.2 version struct

func CanonicalTime Uses

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

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

func Clean Uses

func Clean(s string) (string, error)

Clean is Replace with an empty replacement string.

func FilterTags Uses

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 Uses

func MustReplace(s, replacement string) string

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

func ParseAbsTime Uses

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 Uses

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

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

func Replace Uses

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 Uses

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 Uses

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 Uses

func ValidTSDBString(s string) bool

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

type Context Uses

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

Context is the interface for querying an OpenTSDB server.

type DataPoint Uses

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 Uses

func (d *DataPoint) Clean() error

func (*DataPoint) MarshalJSON Uses

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

MarshalJSON verifies d is valid and converts it to JSON.

func (*DataPoint) Valid Uses

func (d *DataPoint) Valid() bool

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

type Duration Uses

type Duration time.Duration

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

func GetDuration Uses

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

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

func ParseDuration Uses

func ParseDuration(s string) (Duration, error)

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

func (Duration) HumanString Uses

func (d Duration) HumanString() string

func (Duration) Seconds Uses

func (d Duration) Seconds() float64

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

func (Duration) String Uses

func (d Duration) String() string

func (*Duration) UnmarshalText Uses

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

type Filter Uses

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

func ParseFilters Uses

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 Uses

func (f Filter) String() string

type Filters Uses

type Filters []Filter

func (Filters) String Uses

func (filters Filters) String() string

type Host Uses

type Host string

Host is a simple OpenTSDB Context with no additional features.

func (Host) Query Uses

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

Query performs the request to the OpenTSDB server.

type LimitContext Uses

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 Uses

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 Uses

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 Uses

func (c *LimitContext) Version() Version

type MultiDataPoint Uses

type MultiDataPoint []*DataPoint

MultiDataPoint holds multiple DataPoints:

type Point Uses

type Point float64

Point is the Response data point type.

type Query Uses

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 Uses

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 Uses

func (q Query) String() string

type RateOptions Uses

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

RateOptions are rate options for a query.

type Request Uses

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 Uses

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

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

func RequestFromJSON Uses

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

RequestFromJSON creates a new request from JSON.

func (*Request) AutoDownsample Uses

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

AutoDownsample sets the avg downsample aggregator to produce l points.

func (*Request) Query Uses

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 Uses

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 Uses

func (r *Request) Search() string

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

func (*Request) SetTime Uses

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 Uses

func (r *Request) String() string

type RequestError Uses

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 Uses

func (r *RequestError) Error() string

type Response Uses

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 Uses

func (r *Response) Copy() *Response

type ResponseSet Uses

type ResponseSet []*Response

ResponseSet is a Multi-Set Response:

func (ResponseSet) Copy Uses

func (r ResponseSet) Copy() ResponseSet

type TagSet Uses

type TagSet map[string]string

TagSet is a helper class for tags.

func ParseTags Uses

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 Uses

func (t TagSet) AllSubsets() []string

func (TagSet) Clean Uses

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 Uses

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 Uses

func (t TagSet) Copy() TagSet

Copy creates a new TagSet from t.

func (TagSet) Equal Uses

func (t TagSet) Equal(o TagSet) bool

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

func (TagSet) Intersection Uses

func (t TagSet) Intersection(o TagSet) TagSet

Intersection returns the intersection of t and o.

func (TagSet) Merge Uses

func (t TagSet) Merge(o TagSet) TagSet

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

func (TagSet) Overlaps Uses

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 Uses

func (t TagSet) String() string

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

func (TagSet) Subset Uses

func (t TagSet) Subset(o TagSet) bool

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

func (TagSet) Tags Uses

func (t TagSet) Tags() string

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

func (TagSet) Valid Uses

func (t TagSet) Valid() bool

Valid returns whether t contains OpenTSDB-submittable tags.

type Version Uses

type Version struct {
    Major int64
    Minor int64

func (Version) FilterSupport Uses

func (v Version) FilterSupport() bool

func (*Version) UnmarshalText Uses

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

Package opentsdb imports 18 packages (graph) and is imported by 47 packages. Updated 2019-08-08. Refresh now. Tools for package owners.