github.com/influxdata/telegraf@v1.30.3/metric.go (about)

     1  package telegraf
     2  
     3  import (
     4  	"time"
     5  )
     6  
     7  // ValueType is an enumeration of metric types that represent a simple value.
     8  type ValueType int
     9  
    10  // Possible values for the ValueType enum.
    11  const (
    12  	_ ValueType = iota
    13  	Counter
    14  	Gauge
    15  	Untyped
    16  	Summary
    17  	Histogram
    18  )
    19  
    20  // Tag represents a single tag key and value.
    21  type Tag struct {
    22  	Key   string
    23  	Value string
    24  }
    25  
    26  // Field represents a single field key and value.
    27  type Field struct {
    28  	Key   string
    29  	Value interface{}
    30  }
    31  
    32  // Metric is the type of data that is processed by Telegraf.  Input plugins,
    33  // and to a lesser degree, Processor and Aggregator plugins create new Metrics
    34  // and Output plugins write them.
    35  //
    36  //nolint:interfacebloat // conditionally allow to contain more methods
    37  type Metric interface {
    38  	// Name is the primary identifier for the Metric and corresponds to the
    39  	// measurement in the InfluxDB data model.
    40  	Name() string
    41  
    42  	// Tags returns the tags as a map.  This method is deprecated, use TagList instead.
    43  	Tags() map[string]string
    44  
    45  	// TagList returns the tags as a slice ordered by the tag key in lexical
    46  	// bytewise ascending order.  The returned value should not be modified,
    47  	// use the AddTag or RemoveTag methods instead.
    48  	TagList() []*Tag
    49  
    50  	// Fields returns the fields as a map.  This method is deprecated, use FieldList instead.
    51  	Fields() map[string]interface{}
    52  
    53  	// FieldList returns the fields as a slice in an undefined order.  The
    54  	// returned value should not be modified, use the AddField or RemoveField
    55  	// methods instead.
    56  	FieldList() []*Field
    57  
    58  	// Time returns the timestamp of the metric.
    59  	Time() time.Time
    60  
    61  	// Type returns a general type for the entire metric that describes how you
    62  	// might interpret, aggregate the values. Used by prometheus and statsd.
    63  	Type() ValueType
    64  
    65  	// SetName sets the metric name.
    66  	SetName(name string)
    67  
    68  	// AddPrefix adds a string to the front of the metric name.  It is
    69  	// equivalent to m.SetName(prefix + m.Name()).
    70  	//
    71  	// This method is deprecated, use SetName instead.
    72  	AddPrefix(prefix string)
    73  
    74  	// AddSuffix appends a string to the back of the metric name.  It is
    75  	// equivalent to m.SetName(m.Name() + suffix).
    76  	//
    77  	// This method is deprecated, use SetName instead.
    78  	AddSuffix(suffix string)
    79  
    80  	// GetTag returns the value of a tag and a boolean to indicate if it was set.
    81  	GetTag(key string) (string, bool)
    82  
    83  	// HasTag returns true if the tag is set on the Metric.
    84  	HasTag(key string) bool
    85  
    86  	// AddTag sets the tag on the Metric.  If the Metric already has the tag
    87  	// set then the current value is replaced.
    88  	AddTag(key, value string)
    89  
    90  	// RemoveTag removes the tag if it is set.
    91  	RemoveTag(key string)
    92  
    93  	// GetField returns the value of a field and a boolean to indicate if it was set.
    94  	GetField(key string) (interface{}, bool)
    95  
    96  	// HasField returns true if the field is set on the Metric.
    97  	HasField(key string) bool
    98  
    99  	// AddField sets the field on the Metric.  If the Metric already has the field
   100  	// set then the current value is replaced.
   101  	AddField(key string, value interface{})
   102  
   103  	// RemoveField removes the tag if it is set.
   104  	RemoveField(key string)
   105  
   106  	// SetTime sets the timestamp of the Metric.
   107  	SetTime(t time.Time)
   108  
   109  	// SetType sets the value-type of the Metric.
   110  	SetType(t ValueType)
   111  
   112  	// HashID returns an unique identifier for the series.
   113  	HashID() uint64
   114  
   115  	// Copy returns a deep copy of the Metric.
   116  	Copy() Metric
   117  
   118  	// Accept marks the metric as processed successfully and written to an
   119  	// output.
   120  	Accept()
   121  
   122  	// Reject marks the metric as processed unsuccessfully.
   123  	Reject()
   124  
   125  	// Drop marks the metric as processed successfully without being written
   126  	// to any output.
   127  	Drop()
   128  }
   129  
   130  // TemplateMetric is an interface to use in templates (e.g text/template)
   131  // to generate complex strings from metric properties
   132  // e.g. '{{.Name}}-{{.Tag "foo"}}-{{.Field "bar"}}'
   133  type TemplateMetric interface {
   134  	Name() string
   135  	Field(key string) interface{}
   136  	Fields() map[string]interface{}
   137  	Tag(key string) string
   138  	Tags() map[string]string
   139  	Time() time.Time
   140  	String() string
   141  }
   142  
   143  type UnwrappableMetric interface {
   144  	// Unwrap allows to access the underlying raw metric if an implementation
   145  	// wraps it in the first place.
   146  	Unwrap() Metric
   147  }
   148  
   149  type TrackingMetric interface {
   150  	// TrackingID returns the ID used for tracking the metric
   151  	TrackingID() TrackingID
   152  	UnwrappableMetric
   153  }