Update readme and changelog for template processor

CHANGELOG.md

@@ -15,6 +15,10 @@
 - [modbus](/plugins/inputs/modbus/README.md) - Contributed by @garciaolais
 - [monit](/plugins/inputs/monit/README.md) - Contributed by @SirishaGopigiri
 
+#### New Processors
+
+- [template](/plugins/processors/template/README.md) - Contributed by @RobMalvern
+
 #### New Outputs
 
 - [warp10](/plugins/outputs/warp10/README.md) - Contributed by @aurrelhebert

README.md

@@ -352,20 +352,21 @@ For documentation on the latest development code see the [documentation index][d
 
 ## Processor Plugins
 
-* [clone](./plugins/processors/clone)
+* [clone](/plugins/processors/clone)
-* [converter](./plugins/processors/converter)
+* [converter](/plugins/processors/converter)
-* [date](./plugins/processors/date)
+* [date](/plugins/processors/date)
-* [enum](./plugins/processors/enum)
+* [enum](/plugins/processors/enum)
-* [override](./plugins/processors/override)
+* [override](/plugins/processors/override)
-* [parser](./plugins/processors/parser)
+* [parser](/plugins/processors/parser)
-* [pivot](./plugins/processors/pivot)
+* [pivot](/plugins/processors/pivot)
-* [printer](./plugins/processors/printer)
+* [printer](/plugins/processors/printer)
-* [regex](./plugins/processors/regex)
+* [regex](/plugins/processors/regex)
-* [rename](./plugins/processors/rename)
+* [rename](/plugins/processors/rename)
-* [strings](./plugins/processors/strings)
+* [strings](/plugins/processors/strings)
-* [tag_limit](./plugins/processors/tag_limit)
+* [tag_limit](/plugins/processors/tag_limit)
-* [topk](./plugins/processors/topk)
+* [template](/plugins/processors/template)
-* [unpivot](./plugins/processors/unpivot)
+* [topk](/plugins/processors/topk)
+* [unpivot](/plugins/processors/unpivot)
 
 ## Aggregator Plugins
 

plugins/processors/all/all.go

@@ -13,6 +13,7 @@ import (
 	_ "github.com/influxdata/telegraf/plugins/processors/rename"
 	_ "github.com/influxdata/telegraf/plugins/processors/strings"
 	_ "github.com/influxdata/telegraf/plugins/processors/tag_limit"
+	_ "github.com/influxdata/telegraf/plugins/processors/template"
 	_ "github.com/influxdata/telegraf/plugins/processors/topk"
 	_ "github.com/influxdata/telegraf/plugins/processors/unpivot"
 )

plugins/processors/template/README.md

@@ -1,26 +1,59 @@
 # Template Processor
 
-The `template` processor applies a go template to tag, field, measurement and time values to create a new tag.
+The `template` processor applies a Go template to metrics to generate a new
+tag.  The primary use case of this plugin is to create a tag that can be used
+for dynamic routing to multiple output plugins or using an output specific
+routing option.
 
-Golang [Template Documentation]
+The template has access to each metric's measurement name, tags, fields, and
+timestamp using the [interface in `/template_metric.go`](template_metric.go).
+
+Read the full [Go Template Documentation][].
 
 ### Configuration
 
 ```toml
-  # Concatenate two tags to create a new tag
 [[processors.template]]
-     ## Tag to create
+  ## Tag to set with the output of the template.
   tag = "topic"
-     ## Template to create tag
+
-     # Note: Single quotes (') are used, so the double quotes (") don't need escaping (\")
+  ## Go template used to create the tag value.  In order to ease TOML
+  ## escaping requirements, you may wish to use single quotes around the
+  ## template string.
   template = '{{ .Tag "hostname" }}.{{ .Tag "level" }}'
 ```
 
 ### Example
 
-```diff
+Combine multiple tags to create a single tag:
-- cpu,level=debug,hostname=localhost value=42i
+```toml
-+ cpu,level=debug,hostname=localhost,topic=localhost.debug value=42i
+[[processors.template]]
+  tag = "topic"
+  template = '{{ .Tag "hostname" }}.{{ .Tag "level" }}'
 ```
 
-[Template Documentation]:https://golang.org/pkg/text/template/
+```diff
+- cpu,level=debug,hostname=localhost time_idle=42
++ cpu,level=debug,hostname=localhost,topic=localhost.debug time_idle=42
+```
+
+Add measurement name as a tag:
+```toml
+[[processors.template]]
+  tag = "measurement"
+  template = '{{ .Name }}'
+```
+
+```diff
+- cpu,hostname=localhost time_idle=42
++ cpu,hostname=localhost,meaurement=cpu time_idle=42
+```
+
+Add the year as a tag, similar to the date processor:
+```toml
+[[processors.template]]
+  tag = "year"
+  template = '{{.Time.UTC.Year}}'
+```
+
+[Go Template Documentation]: https://golang.org/pkg/text/template/

plugins/processors/template/template.go

@@ -1,26 +1,28 @@
 package template
 
 import (
-	"github.com/influxdata/telegraf"
-	"github.com/influxdata/telegraf/plugins/processors"
 	"strings"
 	"text/template"
+
+	"github.com/influxdata/telegraf"
+	"github.com/influxdata/telegraf/plugins/processors"
 )
 
 type TemplateProcessor struct {
 	Tag      string          `toml:"tag"`
 	Template string          `toml:"template"`
+	Log      telegraf.Logger `toml:"-"`
 	tmpl     *template.Template
 }
 
 const sampleConfig = `
-  ## Concatenate two tags to create a new tag
+  ## Tag to set with the output of the template.
-  # [[processors.template]]
+  tag = "topic"
-  #   ## Tag to create
+
-  #   tag = "topic"
+  ## Go template used to create the tag value.  In order to ease TOML
-  #   ## Template to create tag
+  ## escaping requirements, you may wish to use single quotes around the
-  # Note: Single quotes (') are used, so the double quotes (") don't need escaping (\")
+  ## template string.
-  #   template = '{{.Tag "hostname"}}.{{ .Tag "level" }}'
+  template = '{{ .Tag "hostname" }}.{{ .Tag "level" }}'
 `
 
 func (r *TemplateProcessor) SampleConfig() string {
@@ -40,7 +42,8 @@ func (r *TemplateProcessor) Apply(in ...telegraf.Metric) []telegraf.Metric {
 		// supply TemplateMetric and Template from configuration to Template.Execute
 		err := r.tmpl.Execute(&b, &newM)
 		if err != nil {
-			panic(err)
+			r.Log.Errorf("failed to execute template: %v", err)
+			continue
 		}
 
 		metric.AddTag(r.Tag, b.String())
@@ -57,7 +60,7 @@ func (r *TemplateProcessor) Init() error {
 }
 
 func init() {
-	processors.Add("printer", func() telegraf.Processor {
+	processors.Add("template", func() telegraf.Processor {
 		return &TemplateProcessor{}
 	})
 }