From 3c79b77afcf9c63d4a6802afd504eed36e6ea606 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Mon, 21 May 2018 16:39:33 -0700 Subject: [PATCH] Update graphite output dataf format docs --- docs/DATA_FORMATS_OUTPUT.md | 67 ++++++++++------------------ plugins/outputs/graphite/README.md | 14 +++--- plugins/outputs/graphite/graphite.go | 6 +-- 3 files changed, 33 insertions(+), 54 deletions(-) diff --git a/docs/DATA_FORMATS_OUTPUT.md b/docs/DATA_FORMATS_OUTPUT.md index f8d8cf466..f4e41c254 100644 --- a/docs/DATA_FORMATS_OUTPUT.md +++ b/docs/DATA_FORMATS_OUTPUT.md @@ -58,9 +58,15 @@ interoperability. ## Graphite -The Graphite data format translates Telegraf metrics into _dot_ buckets. A -template can be specified for the output of Telegraf metrics into Graphite -buckets. The default template is: +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`](#graphite-tag-support) option. When set, the tag support +method is used, otherwise the [`template` pattern](#template-pattern) is used. + +#### Template Pattern + +The `template` option describes how Telegraf traslates metrics into _dot_ +buckets. The default template is: ``` template = "host.tags.measurement.field" @@ -77,7 +83,7 @@ tag keys are filled. 1. _measurement_ is a special keyword that outputs the measurement name. 1. _field_ is a special keyword that outputs the field name. -Which means the following influx metric -> graphite conversion would happen: +**Example Conversion**: ``` cpu,cpu=cpu-total,dc=us-east-1,host=tars usage_idle=98.09,usage_user=0.89 1455320660004257758 @@ -89,8 +95,17 @@ tars.cpu-total.us-east-1.cpu.usage_idle 98.09 1455320690 Fields with string values will be skipped. Boolean fields will be converted to 1 (true) or 0 (false). -With enable `graphite_tag_support` option following influx metric -> graphite conversion would happen: +#### 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](http://graphite.readthedocs.io/en/latest/tags.html) +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 => @@ -111,47 +126,13 @@ cpu.usage_idle;cpu=cpu-total;dc=us-east-1;host=tars 98.09 1455320690 ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md data_format = "graphite" - # prefix each graphite bucket + ## Prefix added to each graphite bucket prefix = "telegraf" - # graphite template + ## Graphite template pattern template = "host.tags.measurement.field" - # Enable Graphite tags support - # Defaults to "false" - graphite_tag_support = true -``` - -## Graphite 1.1 - -The Graphite11 data format translates Telegraf metrics into Graphite protocol which supports storing data using tags to identify each series. [Graphite Tag Support](http://graphite.readthedocs.io/en/latest/tags.html) - -Which means the following influx metric -> graphite 1.1.x conversion would happen: - -``` -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 -``` - -Fields with string values will be skipped. Boolean fields will be converted -to 1 (true) or 0 (false). - -### Graphite Configuration - -```toml -[[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 = "graphite11" - - # prefix each graphite bucket - prefix = "telegraf" + ## Support Graphite tags, recommended to enable when using Graphite 1.1 or later. + # graphite_tag_support = false ``` ## JSON diff --git a/plugins/outputs/graphite/README.md b/plugins/outputs/graphite/README.md index c54f07bb1..878eb8048 100644 --- a/plugins/outputs/graphite/README.md +++ b/plugins/outputs/graphite/README.md @@ -3,12 +3,10 @@ This plugin writes to [Graphite](http://graphite.readthedocs.org/en/latest/index.html) via raw TCP. - +For details on the translation between Telegraf Metrics and Graphite output, +see the [Graphite Data Format](../../../docs/DATA_FORMATS_OUTPUT.md) - -## Configuration: +### Configuration: ```toml # Configuration for Graphite server to send metrics to @@ -22,10 +20,10 @@ When `graphite_tag_support` is enabled, `name` as tag name is reserved for graph ## Graphite output template ## see https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md template = "host.tags.measurement.field" + ## Enable Graphite tags support - ## see http://graphite.readthedocs.io/en/latest/tags.html - ## Defaults to "false" - # graphite_tag_support = true + # graphite_tag_support = false + ## timeout in seconds for the write connection to graphite timeout = 2 diff --git a/plugins/outputs/graphite/graphite.go b/plugins/outputs/graphite/graphite.go index 8931dbe0a..c26c1587f 100644 --- a/plugins/outputs/graphite/graphite.go +++ b/plugins/outputs/graphite/graphite.go @@ -36,10 +36,10 @@ var sampleConfig = ` ## Graphite output template ## see https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_OUTPUT.md template = "host.tags.measurement.field" + ## Enable Graphite tags support - ## see http://graphite.readthedocs.io/en/latest/tags.html - ## Defaults to "false" - # graphite_tag_support = true + # graphite_tag_support = false + ## timeout in seconds for the write connection to graphite timeout = 2