carbon2

README

Carbon2

The carbon2 serializer translates the Telegraf metric format to the Carbon2 format.

Configuration

[[outputs.file]]
  ## Files to write to, "stdout" is a specially handled file.
  files = ["stdout", "/tmp/metrics.out"]

  ## 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_OUTPUT.md
  data_format = "carbon2"

  ## Optionally configure metrics format, whether to merge metric name and field name.
  ## Possible options:
  ## * "field_separate"
  ## * "metric_includes_field"
  ## * "" - defaults to "field_separate"
  # carbon2_format = "field_separate"

  ## Character used for replacing sanitized characters. By default ":" is used.
  ## The following character set is being replaced with sanitize replace char:
  ## !@#$%^&*()+`'\"[]{};<>,?/\\|=
  # carbon2_sanitize_replace_char = ":"

Standard form:

metric=name field=field_1 host=foo  30 1234567890
metric=name field=field_2 host=foo  4 1234567890
metric=name field=field_N host=foo  59 1234567890

Metrics format

Carbon2 serializer has a configuration option - carbon2_format - to change how metrics names are being constructed.

By default metric will only include the metric name and a separate field field will contain the field name. This is the behavior of carbon2_format = "field_separate" which is the default behavior (even if unspecified).

Optionally user can opt in to change this to make the metric include the field name after the _. This is the behavior of carbon2_format = "metric_includes_field" which would make the above example look like:

metric=name_field_1 host=foo  30 1234567890
metric=name_field_2 host=foo  4 1234567890
metric=name_field_N host=foo  59 1234567890

Metric name sanitization

In order to sanitize the metric name one can specify carbon2_sanitize_replace_char in order to replace the following characters in the metric name:

!@#$%^&*()+`'\"[]{};<>,?/\\|=

By default they will be replaced with :.

Metrics

The serializer converts the metrics by creating intrinsic_tags using the combination of metric name and fields. So, if one Telegraf metric has 4 fields, the carbon2 output will be 4 separate metrics. There will be a metric tag that represents the name of the metric and a field tag to represent the field.

Example

If we take the following InfluxDB Line Protocol:

weather,location=us-midwest,season=summer temperature=82,wind=100 1234567890

after serializing in Carbon2, the result would be:

metric=weather field=temperature location=us-midwest season=summer  82 1234567890
metric=weather field=wind location=us-midwest season=summer  100 1234567890

Fields and Tags with spaces

When a field key or tag key/value have spaces, spaces will be replaced with _.

Tags with empty values

When a tag's value is empty, it will be replaced with null

Documentation

Index

• 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)

Types

type Serializer

type Serializer struct {
	Format              string          `toml:"carbon2_format"`
	SanitizeReplaceChar string          `toml:"carbon2_sanitize_replace_char"`
	Log                 telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

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)