Improve documentation for the Metric interface (#7256)

This commit is contained in:
Daniel Nelson 2020-04-03 10:11:41 -07:00 committed by GitHub
parent fb0fee0fbb
commit 71a67ef227
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 61 additions and 5 deletions

View File

@ -17,43 +17,93 @@ const (
Histogram
)
// Tag represents a single tag key and value.
type Tag struct {
Key string
Value string
}
// Field represents a single field key and value.
type Field struct {
Key string
Value interface{}
}
// Metric is the type of data that is processed by Telegraf. Input plugins,
// and to a lesser degree, Processor and Aggregator plugins create new Metrics
// and Output plugins write them.
type Metric interface {
// Getting data structure functions
// Name is the primary identifier for the Metric and corresponds to the
// measurement in the InfluxDB data model.
Name() string
// Tags returns the tags as a map. This method is deprecated, use TagList instead.
Tags() map[string]string
// TagList returns the tags as a slice ordered by the tag key in lexical
// bytewise ascending order. The returned value should not be modified,
// use the AddTag or RemoveTag methods instead.
TagList() []*Tag
// Fields returns the fields as a map. This method is deprecated, use FieldList instead.
Fields() map[string]interface{}
// FieldList returns the fields as a slice in an undefined order. The
// returned value should not be modified, use the AddField or RemoveField
// methods instead.
FieldList() []*Field
// Time returns the timestamp of the metric.
Time() time.Time
// Type returns a general type for the entire metric that describes how you
// might interprete, aggregate the values.
//
// This method may be removed in the future and its use is discouraged.
Type() ValueType
// Name functions
// SetName sets the metric name.
SetName(name string)
// AddPrefix adds a string to the front of the metric name. It is
// equivalent to m.SetName(prefix + m.Name()).
//
// This method is deprecated, use SetName instead.
AddPrefix(prefix string)
// AddSuffix appends a string to the back of the metric name. It is
// equivalent to m.SetName(m.Name() + suffix).
//
// This method is deprecated, use SetName instead.
AddSuffix(suffix string)
// Tag functions
// GetTag returns the value of a tag and a boolean to indicate if it was set.
GetTag(key string) (string, bool)
// HasTag returns true if the tag is set on the Metric.
HasTag(key string) bool
// AddTag sets the tag on the Metric. If the Metric already has the tag
// set then the current value is replaced.
AddTag(key, value string)
// RemoveTag removes the tag if it is set.
RemoveTag(key string)
// Field functions
// GetField returns the value of a field and a boolean to indicate if it was set.
GetField(key string) (interface{}, bool)
// HasField returns true if the field is set on the Metric.
HasField(key string) bool
// AddField sets the field on the Metric. If the Metric already has the field
// set then the current value is replaced.
AddField(key string, value interface{})
// RemoveField removes the tag if it is set.
RemoveField(key string)
// SetTime sets the timestamp of the Metric.
SetTime(t time.Time)
// HashID returns an unique identifier for the series.
@ -73,7 +123,13 @@ type Metric interface {
// to any output.
Drop()
// Mark Metric as an aggregate
// SetAggregate indicates the metric is an aggregated value.
//
// This method may be removed in the future and its use is discouraged.
SetAggregate(bool)
// IsAggregate returns true if the Metric is an aggregate.
//
// This method may be removed in the future and its use is discouraged.
IsAggregate() bool
}