diff --git a/PLUGINS.md b/PLUGINS.md index b5d26ce6c..50bb1c713 100644 --- a/PLUGINS.md +++ b/PLUGINS.md @@ -28,7 +28,8 @@ type Plugin interface { } type Accumulator interface { - Add(name string, value interface{}, tags map[string]string) + Add(name string, value interface{}, tags map[string]string) + AddValuesWithTime(name string, values map[string]interface{}, tags map[string]string, timestamp time.Time) } ``` @@ -38,15 +39,19 @@ The way that a plugin emits metrics is by interacting with the Accumulator. The `Add` function takes 3 arguments: * **name**: A string which names the metric. For instance `bytes_read` or `faults`. -* **value**: A value for the metric. Ths accepts 5 different types of value: +* **value**: A value for the metric. This accepts 5 different types of value: * **int**: The most common type. All int types are accepted but favor using `int64` Useful for counters, etc. * **float**: Favor `float64`, useful for gauges, percentages, etc. * **bool**: `true` or `false`, useful to indicate the presence of a state. `light_on`, etc. * **string**: Typically used to indicate a message, or some kind of freeform information. - * **time.Time**: Useful for indicating when a state last occured, for instance `light_on_since`. + * **time.Time**: Useful for indicating when a state last occurred, for instance `light_on_since`. * **tags**: This is a map of strings to strings to describe the where or who about the metric. For instance, the `net` plugin adds a tag named `"interface"` set to the name of the network interface, like `"eth0"`. +The `AddValuesWithTime` allows multiple values for a point to be passed. The values +used are the same type profile as **value** above. The **timestamp** argument +allows a point to be registered as having occurred at an arbitrary time. + Let's say you've written a plugin that emits metrics abuot processes on the current host. ```go diff --git a/accumulator.go b/accumulator.go index 8893642e0..0ef0f418e 100644 --- a/accumulator.go +++ b/accumulator.go @@ -4,6 +4,7 @@ import ( "fmt" "sort" "strings" + "time" "github.com/influxdb/influxdb/client" ) @@ -36,7 +37,7 @@ func (bp *BatchPoints) Add(name string, val interface{}, tags map[string]string) sort.Strings(tg) - fmt.Printf("> [%s] %s=%v\n", strings.Join(tg, " "), name, val) + fmt.Printf("> [%s] %s value=%v\n", strings.Join(tg, " "), name, val) } bp.Points = append(bp.Points, client.Point{ @@ -47,3 +48,44 @@ func (bp *BatchPoints) Add(name string, val interface{}, tags map[string]string) }, }) } + +func (bp *BatchPoints) AddValuesWithTime( + name string, + values map[string]interface{}, + tags map[string]string, + timestamp time.Time, +) { + name = bp.Prefix + name + + if bp.Config != nil { + if !bp.Config.ShouldPass(name) { + return + } + } + + if bp.Debug { + var tg []string + + for k, v := range tags { + tg = append(tg, fmt.Sprintf("%s=\"%s\"", k, v)) + } + + var vals []string + + for k, v := range values { + vals = append(vals, fmt.Sprintf("%s=%v", k, v)) + } + + sort.Strings(tg) + sort.Strings(vals) + + fmt.Printf("> [%s] %s %s\n", strings.Join(tg, " "), name, strings.Join(vals, " ")) + } + + bp.Points = append(bp.Points, client.Point{ + Name: name, + Tags: tags, + Fields: values, + Time: timestamp, + }) +} diff --git a/plugins/registry.go b/plugins/registry.go index 632f54c24..fcee0a765 100644 --- a/plugins/registry.go +++ b/plugins/registry.go @@ -1,7 +1,22 @@ package plugins +import "time" + type Accumulator interface { + // Create a named point with a value, decorating it with named tags + // NOTE: tags is expected to be owned by the caller, don't mutate + // it after passing to Add. Add(name string, value interface{}, tags map[string]string) + + // Create a named point with a set of values, decorating it with named tags + // NOTE: tags and values are expected to be owned by the caller, don't mutate + // them after passing to AddValuesWithTime. + AddValuesWithTime( + name string, + values map[string]interface{}, + tags map[string]string, + timestamp time.Time, + ) } type Plugin interface { diff --git a/testutil/accumulator.go b/testutil/accumulator.go index 2ac4c4849..310a2bd3b 100644 --- a/testutil/accumulator.go +++ b/testutil/accumulator.go @@ -1,11 +1,16 @@ package testutil -import "fmt" +import ( + "fmt" + "time" +) type Point struct { - Name string - Value interface{} - Tags map[string]string + Name string + Value interface{} + Tags map[string]string + Values map[string]interface{} + Time time.Time } type Accumulator struct { @@ -13,7 +18,31 @@ type Accumulator struct { } func (a *Accumulator) Add(name string, value interface{}, tags map[string]string) { - a.Points = append(a.Points, &Point{name, value, tags}) + a.Points = append( + a.Points, + &Point{ + Name: name, + Value: value, + Tags: tags, + }, + ) +} + +func (a *Accumulator) AddValuesWithTime( + name string, + values map[string]interface{}, + tags map[string]string, + timestamp time.Time, +) { + a.Points = append( + a.Points, + &Point{ + Name: name, + Values: values, + Tags: tags, + Time: timestamp, + }, + ) } func (a *Accumulator) Get(name string) (*Point, bool) {