collectd.org – collectd.org/api Index | Examples | Files

package api

import "collectd.org/api"

Package api defines data types representing core collectd data types.

Package api defines data types representing core collectd data types.

Index

Examples

Variables 

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

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 

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" 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))
}

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.

Source Files

json.go main.go types.go

Version
v0.6.0 (latest)
Published
Jan 4, 2024
Platform
linux/amd64
Imports
15 packages
Last checked
2 months ago –

Tools for package owners.