136 lines
3.3 KiB
Markdown
136 lines
3.3 KiB
Markdown
# 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:
|
|
```
|
|
"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:** `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.
|
|
|
|
```
|
|
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.
|
|
|
|
```
|
|
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.
|
|
|
|
```
|
|
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:
|
|
|
|
```
|
|
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.
|
|
|
|
```
|
|
cpu.usage.idle.eu-east 100
|
|
=> cpu_usage,region=eu-east,datacenter=1a idle=100
|
|
```
|
|
|
|
[metrics]: /docs/METRICS.md
|