Back to godoc.org

Package api

v0.5.0
Latest Go to latest
Published: Jun 5, 2020 | License: ISC | Module: github.com/collectd/go-collectd

Overview

Package api defines data types representing core collectd data types.

Package api defines data types representing core collectd data types.

Index

Examples

Package Files

Variables

var (
	// ErrNoDataset is returned when the data set cannot be found.
	ErrNoDataset = errors.New("no such dataset")
)

type Counter

type Counter uint64

Counter represents a counter metric value, such as bytes sent over the network. When a counter value is smaller than the previous value, a wrap around (overflow) is assumed. This causes huge spikes in case a counter is reset. Only use Counter for very specific cases. If in doubt, use Derive instead. This is Go's equivalent to the C type "counter_t".

func (Counter) Type

func (v Counter) Type() string

Type returns "counter".

type DataSet

type DataSet struct {
	Name    string
	Sources []DataSource
}

DataSet defines the metrics of a given "Type", i.e. the name, kind (Derive, Gauge, …) and minimum and maximum values.

func (*DataSet) Check

func (ds *DataSet) Check(vl *ValueList) error

Check does sanity checking of vl and returns an error if it finds a problem. Sanity checking includes checking the concrete types in the Values slice against the DataSet's Sources.

func (*DataSet) Names

func (ds *DataSet) Names() []string

Names returns a slice of the data source names. This can be used to populate ValueList.DSNames.

func (*DataSet) Values

func (ds *DataSet) Values(args ...interface{}) ([]Value, error)

Values converts the arguments to the Value interface type and returns them as a slice. It expects the same number of arguments as it has Sources and will return an error if there is a mismatch. Each argument is converted to a Counter, Derive or Gauge according to the corresponding DataSource.Type.

type DataSource

type DataSource struct {
	Name     string
	Type     reflect.Type
	Min, Max float64
}

DataSource defines one metric within a "Type" / DataSet. Type is one of Counter, Derive and Gauge. Min and Max apply to the rates of Counter and Derive types, not the raw incremental value.

func (DataSource) Value

func (dsrc DataSource) Value(arg interface{}) (Value, error)

Value converts arg to a Counter, Derive or Gauge and returns it as the Value interface type. Returns an error if arg cannot be converted.

type Derive

type Derive int64

Derive represents a counter metric value, such as bytes sent over the network. When the counter wraps around (overflows) or is reset, this is interpreted as a (huge) negative rate, which is discarded. This is Go's equivalent to the C type "derive_t".

func (Derive) Type

func (v Derive) Type() string

Type returns "derive".

type Fanout

type Fanout []Writer

Fanout implements a multiplexer for Writer, i.e. each ValueList written to it is copied and written to each Writer.

func (Fanout) Write

func (f Fanout) Write(ctx context.Context, vl *ValueList) error

Write writes the value list to each writer. Each writer receives a copy of the value list to avoid writers interfering with one another. Writers are executed concurrently. Write blocks until all writers have returned and returns an error containing all errors returned by writers.

If the context is canceled, Write returns an error immediately. Since it may return before all writers have finished, the returned error may not contain the error of all writers.

type Gauge

type Gauge float64

Gauge represents a gauge metric value, such as a temperature. This is Go's equivalent to the C type "gauge_t".

func (Gauge) Type

func (v Gauge) Type() string

Type returns "gauge".

type Identifier

type Identifier struct {
	Host                   string
	Plugin, PluginInstance string
	Type, TypeInstance     string
}

Identifier identifies one metric.

func ParseIdentifier

func ParseIdentifier(s string) (Identifier, error)

ParseIdentifier parses the identifier encoded in s and returns it.

func (Identifier) String

func (id Identifier) String() string

String returns a string representation of the Identifier.

type TypesDB

type TypesDB struct {
	// contains filtered or unexported fields
}

TypesDB holds the type definitions of one or more types.db(5) files.

func NewTypesDB

func NewTypesDB(r io.Reader) (*TypesDB, error)

NewTypesDB parses collectd's types.db file and returns an initialized TypesDB object that can be queried.

func (*TypesDB) DataSet

func (db *TypesDB) DataSet(typ string) (*DataSet, bool)

DataSet returns the DataSet "typ". This is similar to collectd's plugin_get_ds() function.

func (*TypesDB) Merge

func (db *TypesDB) Merge(other *TypesDB)

Merge adds all entries in other to db, possibly overwriting entries in db with the same name.

func (*TypesDB) ValueList

func (db *TypesDB) ValueList(id Identifier, t time.Time, interval time.Duration, values ...interface{}) (*ValueList, error)

ValueList initializes and returns a new ValueList. The number of values arguments must match the number of DataSources in the vl.Type DataSet and are converted to []Value using DataSet.Values().

type Value

type Value interface {
	Type() string
}

Value represents either a Gauge or a Derive. It is Go's equivalent to the C union value_t. If a function accepts a Value, you may pass in either a Gauge or a Derive. Passing in any other type may or may not panic.

type ValueList

type ValueList struct {
	Identifier
	Time     time.Time
	Interval time.Duration
	Values   []Value
	DSNames  []string
	Meta     meta.Data
}

ValueList represents one (set of) data point(s) of one metric. It is Go's equivalent of the C type value_list_t.

func (*ValueList) Clone

func (vl *ValueList) Clone() *ValueList

Clone returns a copy of vl. Unfortunately, many functions expect a pointer to a value list. If the original value list must not be modified, it may be necessary to create and pass a copy. This is what this method helps to do.

func (*ValueList) DSName

func (vl *ValueList) DSName(index int) string

DSName returns the name of the data source at the given index. If vl.DSNames is nil, returns "value" if there is a single value and a string representation of index otherwise.

func (*ValueList) MarshalJSON

func (vl *ValueList) MarshalJSON() ([]byte, error)

MarshalJSON implements the "encoding/json".Marshaler interface for ValueList.

func (*ValueList) UnmarshalJSON

func (vl *ValueList) UnmarshalJSON(data []byte) error

UnmarshalJSON implements the "encoding/json".Unmarshaler interface for ValueList.

Please note that this function is currently not compatible with write_http's "StoreRates" setting: if enabled, write_http converts derives and counters to a rate (a floating point number), but still puts "derive" or "counter" in the "dstypes" array. UnmarshalJSON will try to parse such values as integers, which will fail in many cases.

Example

Code:

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
	data, err := ioutil.ReadAll(r.Body)
	if err != nil {
		log.Printf("while reading body: %v", err)
		http.Error(w, err.Error(), http.StatusInternalServerError)
		return
	}

	var vls []*ValueList
	if err := json.Unmarshal(data, &vls); err != nil {
		log.Printf("while parsing JSON: %v", err)
		http.Error(w, err.Error(), http.StatusBadRequest)
		return
	}

	for _, vl := range vls {
		var w Writer
		w.Write(r.Context(), vl)

	}

	w.WriteHeader(http.StatusNoContent)
})

log.Fatal(http.ListenAndServe(":8080", nil))

type Writer

type Writer interface {
	Write(context.Context, *ValueList) error
}

Writer are objects accepting a ValueList for writing, for example to the network.

type WriterFunc

type WriterFunc func(context.Context, *ValueList) error

WriterFunc implements the Writer interface based on a wrapped function.

func (WriterFunc) Write

func (f WriterFunc) Write(ctx context.Context, vl *ValueList) error

Write calls the wrapped function.

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier