From 5f2f2ff33d5c6bc810f8b66dcbee515cc03a3759 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Thu, 6 Feb 2020 13:34:36 -0800 Subject: [PATCH] Update readme and changelog for template processor --- CHANGELOG.md | 4 ++ README.md | 29 ++++++------ plugins/processors/all/all.go | 1 + plugins/processors/template/README.md | 59 +++++++++++++++++++------ plugins/processors/template/template.go | 29 ++++++------ 5 files changed, 82 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e996aa8bf..350a7530a 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 7df2067cc..0df0f003c 100644 --- a/README.md +++ b/README.md @@ -352,20 +352,21 @@ For documentation on the latest development code see the [documentation index][d ## Processor Plugins -* [clone](./plugins/processors/clone) -* [converter](./plugins/processors/converter) -* [date](./plugins/processors/date) -* [enum](./plugins/processors/enum) -* [override](./plugins/processors/override) -* [parser](./plugins/processors/parser) -* [pivot](./plugins/processors/pivot) -* [printer](./plugins/processors/printer) -* [regex](./plugins/processors/regex) -* [rename](./plugins/processors/rename) -* [strings](./plugins/processors/strings) -* [tag_limit](./plugins/processors/tag_limit) -* [topk](./plugins/processors/topk) -* [unpivot](./plugins/processors/unpivot) +* [clone](/plugins/processors/clone) +* [converter](/plugins/processors/converter) +* [date](/plugins/processors/date) +* [enum](/plugins/processors/enum) +* [override](/plugins/processors/override) +* [parser](/plugins/processors/parser) +* [pivot](/plugins/processors/pivot) +* [printer](/plugins/processors/printer) +* [regex](/plugins/processors/regex) +* [rename](/plugins/processors/rename) +* [strings](/plugins/processors/strings) +* [tag_limit](/plugins/processors/tag_limit) +* [template](/plugins/processors/template) +* [topk](/plugins/processors/topk) +* [unpivot](/plugins/processors/unpivot) ## Aggregator Plugins diff --git a/plugins/processors/all/all.go b/plugins/processors/all/all.go index e0f69d787..ba72ee10e 100644 --- a/plugins/processors/all/all.go +++ b/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" ) diff --git a/plugins/processors/template/README.md b/plugins/processors/template/README.md index bd336f045..f08a96c6b 100644 --- a/plugins/processors/template/README.md +++ b/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/ \ No newline at end of file +```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/ diff --git a/plugins/processors/template/template.go b/plugins/processors/template/template.go index 20da631a8..f4470a07c 100644 --- a/plugins/processors/template/template.go +++ b/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{} }) }