api

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Jan 4, 2024 License: ISC Imports: 15 Imported by: 79

Documentation

Overview

Package api defines data types representing core collectd data types.

Package api defines data types representing core collectd data types.

Index

Examples

Constants

This section is empty.

Variables

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

Functions

This section is empty.

Types

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.4.0

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 added in v0.4.0

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 added in v0.2.0

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

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

func NewTypesDB added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.4.0

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
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" is a placeholder to avoid cyclic dependencies.
		// In real live, you'd do something like this here:
		// exec.Putval.Write(vl)
	}

	w.WriteHeader(http.StatusNoContent)
})

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

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 added in v0.4.0

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

WriterFunc implements the Writer interface based on a wrapped function.

func (WriterFunc) Write added in v0.4.0

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

Write calls the wrapped function.

Jump to

Keyboard shortcuts

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