graphite

README

Graphite

The Graphite data format is translated from Telegraf Metrics using either the template pattern or tag support method. You can select between the two methods using the graphite_tag_support option. When set, the tag support method is used, otherwise the Template Pattern is used.

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 = "graphite"

  ## Prefix added to each graphite bucket
  prefix = "telegraf"
  ## Graphite template pattern
  template = "host.tags.measurement.field"

  ## Graphite templates patterns
  ## 1. Template for cpu
  ## 2. Template for disk*
  ## 3. Default template
  # templates = [
  #  "cpu tags.measurement.host.field",
  #  "disk* measurement.field",
  #  "host.measurement.tags.field"
  #]

  ## Strict sanitization regex
  ## This is the default sanitization regex that is used on data passed to the
  ## graphite serializer. Users can add additional characters here if required.
  ## Be aware that the characters, '/' '@' '*' are always replaced with '_',
  ## '..' is replaced with '.', and '\' is removed even if added to the
  ## following regex.
  # graphite_strict_sanitize_regex = '[^a-zA-Z0-9-:._=\p{L}]'

  ## Support Graphite tags, recommended to enable when using Graphite 1.1 or later.
  # graphite_tag_support = false

  ## Applied sanitization mode when graphite tag support is enabled.
  ## * strict - uses the regex specified above
  ## * compatible - allows for greater number of characters
  # graphite_tag_sanitize_mode = "strict"

  ## Character for separating metric name and field for Graphite tags
  # graphite_separator = "."

graphite_tag_support

When the graphite_tag_support option is enabled, the template pattern is not used. Instead, tags are encoded using Graphite tag support added in Graphite 1.1. The metric_path is a combination of the optional prefix option, measurement name, and field name.

The tag name is reserved by Graphite, any conflicting tags and will be encoded as _name.

Example Conversion:

cpu,cpu=cpu-total,dc=us-east-1,host=tars usage_idle=98.09,usage_user=0.89 1455320660004257758
=>
cpu.usage_user;cpu=cpu-total;dc=us-east-1;host=tars 0.89 1455320690
cpu.usage_idle;cpu=cpu-total;dc=us-east-1;host=tars 98.09 1455320690

With set option graphite_separator to "_"

cpu,cpu=cpu-total,dc=us-east-1,host=tars usage_idle=98.09,usage_user=0.89 1455320660004257758
=>
cpu_usage_user;cpu=cpu-total;dc=us-east-1;host=tars 0.89 1455320690
cpu_usage_idle;cpu=cpu-total;dc=us-east-1;host=tars 98.09 1455320690

The graphite_tag_sanitize_mode option defines how we should sanitize the tag names and values. Possible values are strict, or compatible, with the default being strict.

When in strict mode Telegraf uses the same rules as metrics when not using tags. When in compatible mode Telegraf allows more characters through, and is based on the Graphite specification:

Tag names must have a length >= 1 and may contain any ascii characters except ;!^=. Tag values must also have a length >= 1, they may contain any ascii characters except ; and the first character must not be ~. UTF-8 characters may work for names and values, but they are not well tested and it is not recommended to use non-ascii characters in metric names or tags. Metric names get indexed under the special tag name, if a metric name starts with one or multiple ~ they simply get removed from the derived tag value because the ~ character is not allowed to be in the first position of the tag value. If a metric name consists of no other characters than ~, then it is considered invalid and may get dropped.

Documentation

Index

• Constants
• func InsertField(bucket, fieldName string) string
• func SerializeBucketName(measurement string, tags map[string]string, template string, prefix string) string
• type GraphiteSerializer
  • func (s *GraphiteSerializer) Serialize(metric telegraf.Metric) ([]byte, error)
  • func (s *GraphiteSerializer) SerializeBatch(metrics []telegraf.Metric) ([]byte, error)
  • func (s *GraphiteSerializer) SerializeBucketNameWithTags(measurement string, tags map[string]string, prefix string, separator string, ...) string
• type GraphiteTemplate
  • func InitGraphiteTemplates(templates []string) ([]*GraphiteTemplate, string, error)

Constants

const DefaultTemplate = "host.tags.measurement.field"

Functions

func InsertField

func InsertField(bucket, fieldName string) string

InsertField takes the bucket string from SerializeBucketName and replaces the FIELDNAME portion. If fieldName == "value", it will simply delete the FIELDNAME portion.

func SerializeBucketName

func SerializeBucketName(
	measurement string,
	tags map[string]string,
	template string,
	prefix string,
) string

SerializeBucketName will take the given measurement name and tags and produce a graphite bucket. It will use the GraphiteSerializer.Template to generate this, or DefaultTemplate.

NOTE: SerializeBucketName replaces the "field" portion of the template with FIELDNAME. It is up to the user to replace this. This is so that SerializeBucketName can be called just once per measurement, rather than once per field. See GraphiteSerializer.InsertField() function.

Types

type GraphiteSerializer

type GraphiteSerializer struct {
	Prefix             string              `json:"prefix"`
	Template           string              `json:"template"`
	StrictAllowedChars *regexp.Regexp      `json:"graphite_strict_sanitize_regex"`
	TagSupport         bool                `json:"graphite_tag_support"`
	TagSanitizeMode    string              `json:"graphite_tag_sanitize_mode"`
	Separator          string              `json:"graphite_separator"`
	Templates          []*GraphiteTemplate `json:"templates"`
}

func (*GraphiteSerializer) Serialize

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

func (*GraphiteSerializer) SerializeBatch

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

func (*GraphiteSerializer) SerializeBucketNameWithTags

func (s *GraphiteSerializer) SerializeBucketNameWithTags(
	measurement string,
	tags map[string]string,
	prefix string,
	separator string,
	field string,
	tagSanitizeMode string,
) string

SerializeBucketNameWithTags will take the given measurement name and tags and produce a graphite bucket. It will use the Graphite11Serializer. http://graphite.readthedocs.io/en/latest/tags.html

type GraphiteTemplate

type GraphiteTemplate struct {
	Filter filter.Filter
	Value  string
}

func InitGraphiteTemplates

func InitGraphiteTemplates(templates []string) ([]*GraphiteTemplate, string, error)