Update readme and changelog for template processor

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 = "topic"
-     ## Template to create tag
-     # Note: Single quotes (') are used, so the double quotes (") don't need escaping (\")
-     template = '{{ .Tag "hostname" }}.{{ .Tag "level" }}'
+[[processors.template]]
+  ## Tag to set with the output of the template.
+  tag = "topic"
+
+  ## 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
-- cpu,level=debug,hostname=localhost value=42i
-+ cpu,level=debug,hostname=localhost,topic=localhost.debug value=42i
+Combine multiple tags to create a single tag:
+```toml
+[[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"`
+	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
-  # [[processors.template]]
-  #   ## Tag to create
-  #   tag = "topic"
-  #   ## Template to create tag
-  # Note: Single quotes (') are used, so the double quotes (") don't need escaping (\")
-  #   template = '{{.Tag "hostname"}}.{{ .Tag "level" }}'
+  ## Tag to set with the output of the template.
+  tag = "topic"
+
+  ## 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" }}'
 `
 
 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{}
 	})
 }