prometheus

README

Prometheus

The prometheus data format converts metrics into the Prometheus text exposition format. When used with the prometheus input, the input should be use the metric_version = 2 option in order to properly round trip metrics.

Warning: When generating histogram and summary types, output may not be correct if the metric spans multiple batches. This issue can be somewhat, but not fully, mitigated by using outputs that support writing in "batch format". When using histogram and summary types, it is recommended to use only the prometheus_client output. Histogram and Summary types also update their expiration time based on the most recently received data. If incoming metrics stop updating specific buckets or quantiles but continue reporting others every bucket/quantile will continue to exist.

Configuration

[[outputs.file]]
  files = ["stdout"]
  use_batch_format = true

  ## Include the metric timestamp on each sample.
  prometheus_export_timestamp = false

  ## Sort prometheus metric families and metric samples.  Useful for
  ## debugging.
  prometheus_sort_metrics = false

  ## Output string fields as metric labels; when false string fields are
  ## discarded.
  prometheus_string_as_label = false

  ## Encode metrics without HELP metadata. This helps reduce the payload
  ## size.
  prometheus_compact_encoding = false

  ## Data format to output.
  ## Each data format has its own unique set of configuration options, read
  ## more about them here:
  ##   https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
  data_format = "prometheus"

  ## Specify the metric type explicitly.
  ## This overrides the metric-type of the Telegraf metric. Globbing is allowed.
  [outputs.file.prometheus_metric_types]
    counter = []
    gauge = []

Metrics

A Prometheus metric is created for each integer, float, boolean or unsigned field. Boolean values are converted to 1.0 for true and 0.0 for false.

The Prometheus metric names are produced by joining the measurement name with the field key. In the special case where the measurement name is prometheus it is not included in the final metric name.

Prometheus labels are produced for each tag.

Note: String fields are ignored and do not produce Prometheus metrics.

Example

Example Input

cpu,cpu=cpu0 time_guest=8022.6,time_system=26145.98,time_user=92512.89 1574317740000000000
cpu,cpu=cpu1 time_guest=8097.88,time_system=25223.35,time_user=96519.58 1574317740000000000
cpu,cpu=cpu2 time_guest=7386.28,time_system=24870.37,time_user=95631.59 1574317740000000000
cpu,cpu=cpu3 time_guest=7434.19,time_system=24843.71,time_user=93753.88 1574317740000000000

Example Output

# HELP cpu_time_guest Telegraf collected metric
# TYPE cpu_time_guest counter
cpu_time_guest{cpu="cpu0"} 9582.54
cpu_time_guest{cpu="cpu1"} 9660.88
cpu_time_guest{cpu="cpu2"} 8946.45
cpu_time_guest{cpu="cpu3"} 9002.31
# HELP cpu_time_system Telegraf collected metric
# TYPE cpu_time_system counter
cpu_time_system{cpu="cpu0"} 28675.47
cpu_time_system{cpu="cpu1"} 27779.34
cpu_time_system{cpu="cpu2"} 27406.18
cpu_time_system{cpu="cpu3"} 27404.97
# HELP cpu_time_user Telegraf collected metric
# TYPE cpu_time_user counter
cpu_time_user{cpu="cpu0"} 99551.84
cpu_time_user{cpu="cpu1"} 103468.52
cpu_time_user{cpu="cpu2"} 102591.45
cpu_time_user{cpu="cpu3"} 100717.05

Documentation

Index

• Variables
• func MetricName(measurement, fieldKey string, valueType telegraf.ValueType) string
• func MetricType(valueType telegraf.ValueType) *dto.MetricType
• func SampleCount(value interface{}) (uint64, bool)
• func SampleSum(value interface{}) (float64, bool)
• func SampleValue(value interface{}) (float64, bool)
• func SanitizeLabelName(name string) (string, bool)
• func SanitizeMetricName(name string) (string, bool)
• type Bucket
• type Collection
  • func NewCollection(config FormatConfig) *Collection
  • func (c *Collection) Add(metric telegraf.Metric, now time.Time)
  • func (c *Collection) Expire(now time.Time, age time.Duration)
  • func (c *Collection) GetEntries() []Entry
  • func (c *Collection) GetMetrics(entry Entry) []*Metric
  • func (c *Collection) GetProto() []*dto.MetricFamily
• type Entry
• type FormatConfig
• type Histogram
• type LabelPair
• type Metric
• type MetricFamily
• type MetricKey
  • func MakeMetricKey(labels []LabelPair) MetricKey
• type MetricTypes
  • func (mt *MetricTypes) DetermineType(name string, m telegraf.Metric) telegraf.ValueType
  • func (mt *MetricTypes) Init() error
• type Quantile
• type Scaler
• type Serializer
  • func (s *Serializer) Init() error
  • func (s *Serializer) InitFromConfig(cfg *serializers.Config) error
  • func (s *Serializer) Serialize(metric telegraf.Metric) ([]byte, error)
  • func (s *Serializer) SerializeBatch(metrics []telegraf.Metric) ([]byte, error)
• type Summary
• type Table
• type TimeFunc

Variables

var LabelNameTable = Table{
	First: &unicode.RangeTable{
		R16: []unicode.Range16{
			{0x0041, 0x005A, 1},
			{0x005F, 0x005F, 1},
			{0x0061, 0x007A, 1},
		},
		LatinOffset: 3,
	},
	Rest: &unicode.RangeTable{
		R16: []unicode.Range16{
			{0x0030, 0x0039, 1},
			{0x0041, 0x005A, 1},
			{0x005F, 0x005F, 1},
			{0x0061, 0x007A, 1},
		},
		LatinOffset: 4,
	},
}

var MetricNameTable = Table{
	First: &unicode.RangeTable{
		R16: []unicode.Range16{
			{0x003A, 0x003A, 1},
			{0x0041, 0x005A, 1},
			{0x005F, 0x005F, 1},
			{0x0061, 0x007A, 1},
		},
		LatinOffset: 4,
	},
	Rest: &unicode.RangeTable{
		R16: []unicode.Range16{
			{0x0030, 0x003A, 1},
			{0x0041, 0x005A, 1},
			{0x005F, 0x005F, 1},
			{0x0061, 0x007A, 1},
		},
		LatinOffset: 4,
	},
}

Functions

func MetricName

func MetricName(measurement, fieldKey string, valueType telegraf.ValueType) string

MetricName returns the Prometheus metric name.

func MetricType

func MetricType(valueType telegraf.ValueType) *dto.MetricType

func SampleCount

func SampleCount(value interface{}) (uint64, bool)

SampleCount converts a field value into a count suitable for a metric family of the Histogram or Summary type.

func SampleSum

func SampleSum(value interface{}) (float64, bool)

SampleSum converts a field value into a sum suitable for a metric family of the Histogram or Summary type.

func SampleValue

func SampleValue(value interface{}) (float64, bool)

SampleValue converts a field value into a value suitable for a simple sample value.

func SanitizeLabelName

func SanitizeLabelName(name string) (string, bool)

SanitizeLabelName checks if the name is a valid Prometheus label name. If not, it attempts to replaces invalid runes with an underscore to create a valid name.

func SanitizeMetricName

func SanitizeMetricName(name string) (string, bool)

SanitizeMetricName checks if the name is a valid Prometheus metric name. If not, it attempts to replaces invalid runes with an underscore to create a valid name.

Types

type Bucket

type Bucket struct {
	Bound float64
	Count uint64
}

type Collection

type Collection struct {
	Entries map[MetricFamily]Entry
	// contains filtered or unexported fields
}

func NewCollection

func NewCollection(config FormatConfig) *Collection

func (*Collection) Add

func (c *Collection) Add(metric telegraf.Metric, now time.Time)

func (*Collection) Expire

func (c *Collection) Expire(now time.Time, age time.Duration)

func (*Collection) GetEntries

func (c *Collection) GetEntries() []Entry

func (*Collection) GetMetrics

func (c *Collection) GetMetrics(entry Entry) []*Metric

func (*Collection) GetProto

func (c *Collection) GetProto() []*dto.MetricFamily

type Entry

type Entry struct {
	Family  MetricFamily
	Metrics map[MetricKey]*Metric
}

type FormatConfig

type FormatConfig struct {
	ExportTimestamp bool `toml:"prometheus_export_timestamp"`
	SortMetrics     bool `toml:"prometheus_sort_metrics"`
	StringAsLabel   bool `toml:"prometheus_string_as_label"`
	// CompactEncoding defines whether to include
	// HELP metadata in Prometheus payload. Setting to true
	// helps to reduce payload size.
	CompactEncoding bool        `toml:"prometheus_compact_encoding"`
	TypeMappings    MetricTypes `toml:"prometheus_metric_types"`
}

type Histogram

type Histogram struct {
	Buckets []Bucket
	Count   uint64
	Sum     float64
}

type LabelPair

type LabelPair struct {
	Name  string
	Value string
}

type Metric

type Metric struct {
	Labels    []LabelPair
	Time      time.Time
	AddTime   time.Time
	Scaler    *Scaler
	Histogram *Histogram
	Summary   *Summary
}

type MetricFamily

type MetricFamily struct {
	Name string
	Type telegraf.ValueType
}

type MetricKey

type MetricKey uint64

func MakeMetricKey

func MakeMetricKey(labels []LabelPair) MetricKey

type MetricTypes

type MetricTypes struct {
	Counter []string `toml:"counter"`
	Gauge   []string `toml:"gauge"`
	// contains filtered or unexported fields
}

func (*MetricTypes) DetermineType

func (mt *MetricTypes) DetermineType(name string, m telegraf.Metric) telegraf.ValueType

func (*MetricTypes) Init

func (mt *MetricTypes) Init() error

type Quantile

type Quantile struct {
	Quantile float64
	Value    float64
}

type Scaler

type Scaler struct {
	Value float64
}

type Serializer

type Serializer struct {
	FormatConfig
}

func (*Serializer) Init

func (s *Serializer) Init() error

func (*Serializer) InitFromConfig

func (s *Serializer) InitFromConfig(cfg *serializers.Config) error

InitFromConfig is a compatibility function to construct the parser the old way

func (*Serializer) Serialize

func (s *Serializer) Serialize(metric telegraf.Metric) ([]byte, error)

func (*Serializer) SerializeBatch

func (s *Serializer) SerializeBatch(metrics []telegraf.Metric) ([]byte, error)

type Summary

type Summary struct {
	Quantiles []Quantile
	Count     uint64
	Sum       float64
}

type Table

type Table struct {
	First *unicode.RangeTable
	Rest  *unicode.RangeTable
}

type TimeFunc

type TimeFunc func() time.Time