Adding upstream version 1.34.4.

Signed-off-by: Daniel Baumann <daniel@debian.org>

docs/TEMPLATE_PATTERN.md

@@ -0,0 +1,137 @@
+# Template Patterns
+
+Template patterns are a mini language that describes how a dot delimited
+string should be mapped to and from [metrics][].
+
+A template has the form:
+
+```text
+"host.mytag.mytag.measurement.measurement.field*"
+```
+
+Where the following keywords can be set:
+
+1. `measurement`: specifies that this section of the graphite bucket corresponds
+to the measurement name. This can be specified multiple times.
+2. `field`: specifies that this section of the graphite bucket corresponds
+to the field name. This can be specified multiple times.
+3. `measurement*`: specifies that all remaining elements of the graphite bucket
+correspond to the measurement name.
+4. `field*`: specifies that all remaining elements of the graphite bucket
+correspond to the field name.
+
+Any part of the template that is not a keyword is treated as a tag key. This
+can also be specified multiple times.
+
+**NOTE:** `measurement` must be specified in your template.
+**NOTE:** `field*` cannot be used in conjunction with `measurement*`.
+
+## Examples
+
+### Measurement & Tag Templates
+
+The most basic template is to specify a single transformation to apply to all
+incoming metrics. So the following template:
+
+```toml
+templates = [
+    "region.region.measurement*"
+]
+```
+
+would result in the following Graphite -> Telegraf transformation.
+
+```text
+us.west.cpu.load 100
+=> cpu.load,region=us.west value=100
+```
+
+Multiple templates can also be specified, but these should be differentiated
+using _filters_ (see below for more details)
+
+```toml
+templates = [
+    "*.*.* region.region.measurement", # <- all 3-part measurements will match this one.
+    "*.*.*.* region.region.host.measurement", # <- all 4-part measurements will match this one.
+]
+```
+
+### Field Templates
+
+The field keyword tells Telegraf to give the metric that field name.
+So the following template:
+
+```toml
+separator = "_"
+templates = [
+    "measurement.measurement.field.field.region"
+]
+```
+
+would result in the following Graphite -> Telegraf transformation.
+
+```text
+cpu.usage.idle.percent.eu-east 100
+=> cpu_usage,region=eu-east idle_percent=100
+```
+
+The field key can also be derived from all remaining elements of the graphite
+bucket by specifying `field*`:
+
+```toml
+separator = "_"
+templates = [
+    "measurement.measurement.region.field*"
+]
+```
+
+which would result in the following Graphite -> Telegraf transformation.
+
+```text
+cpu.usage.eu-east.idle.percentage 100
+=> cpu_usage,region=eu-east idle_percentage=100
+```
+
+### Filter Templates
+
+Users can also filter the template(s) to use based on the name of the bucket,
+using glob matching, like so:
+
+```toml
+templates = [
+    "cpu.* measurement.measurement.region",
+    "mem.* measurement.measurement.host"
+]
+```
+
+which would result in the following transformation:
+
+```text
+cpu.load.eu-east 100
+=> cpu_load,region=eu-east value=100
+
+mem.cached.localhost 256
+=> mem_cached,host=localhost value=256
+```
+
+### Adding Tags
+
+Additional tags can be added to a metric that don't exist on the received metric.
+You can add additional tags by specifying them after the pattern.
+Tags have the same format as the line protocol.
+Multiple tags are separated by commas.
+
+```toml
+templates = [
+    "measurement.measurement.field.region datacenter=1a"
+]
+```
+
+would result in the following Graphite -> Telegraf transformation.
+
+```text
+cpu.usage.idle.eu-east 100
+=> cpu_usage,region=eu-east,datacenter=1a idle=100
+```
+
+[metrics]: /docs/METRICS.md