diff --git a/docs/configuration/template_examples.md b/docs/configuration/template_examples.md new file mode 100644 index 0000000000..1710c99f89 --- /dev/null +++ b/docs/configuration/template_examples.md @@ -0,0 +1,116 @@ +--- +title: Template examples +sort_rank: 4 +--- + +# Template examples + +Prometheus supports templating in the summary and description fields of +alerts, as well as in served console pages. Templates have the ability to run +queries against the local database, iterate over data, use conditionals, format +data, etc. The Prometheus templating language is based on the +[Go templating](http://golang.org/pkg/text/template/) system. + +## Simple alert field templates + + ALERT InstanceDown + IF up == 0 + FOR 5m + LABELS { + severity="page" + } + ANNOTATIONS { + summary = "Instance {{$labels.instance}} down", + description = "{{$labels.instance}} of job {{$labels.job}} has been down for more than 5 minutes.", + } + +Alert field templates will be executed during every rule iteration for each +alert that fires, so keep any queries and templates lightweight. If you have a +need for more complicated templates for alerts, it is recommended to link to a +console instead. + +## Simple iteration + +This displays a list of instances, and whether they are up: + +```go +{{ range query "up" }} + {{ .Labels.instance }} {{ .Value }} +{{ end }} +``` + +The special `.` variable contains the value of the current sample for each loop iteration. + +## Display one value + +```go +{{ with query "some_metric{instance='someinstance'}" }} + {{ . | first | value | humanize }} +{{ end }} +``` + +Go and Go's templating language are both strongly typed, so one must check that +samples were returned to avoid an execution error. For example this could +happen if a scrape or rule evaluation has not run yet, or a host was down. + +The included `prom_query_drilldown` template handles this, allows for +formatting of results, and linking to the [expression browser](https://prometheus.io/docs/visualization/browser/). + +## Using console URL parameters + +```go +{{ with printf "node_memory_MemTotal{job='node',instance='%s'}" .Params.instance | query }} + {{ . | first | value | humanize1024}}B +{{ end }} +``` + +If accessed as `console.html?instance=hostname`, `.Params.instance` will evaluate to `hostname`. + +## Advanced iteration + +```html + +{{ range printf "node_network_receive_bytes{job='node',instance='%s',device!='lo'}" .Params.instance | query | sortByLabel "device"}} + + + + + + + + + {{ end }} +
{{ .Labels.device }}
Received{{ with printf "rate(node_network_receive_bytes{job='node',instance='%s',device='%s'}[5m])" .Labels.instance .Labels.device | query }}{{ . | first | value | humanize }}B/s{{end}}
Transmitted{{ with printf "rate(node_network_transmit_bytes{job='node',instance='%s',device='%s'}[5m])" .Labels.instance .Labels.device | query }}{{ . | first | value | humanize }}B/s{{end}}
+``` + +Here we iterate over all network devices and display the network traffic for each. + +As the `range` action does not specify a variable, `.Params.instance` is not +available inside the loop as `.` is now the loop variable. + +## Defining reusable templates + +Prometheus supports defining templates that can be reused. This is particularly +powerful when combined with +[console library](template_reference.md#console-templates) support, allowing +sharing of templates across consoles. + +```go +{{/* Define the template */}} +{{define "myTemplate"}} + do something +{{end}} + +{{/* Use the template */}} +{{template "myTemplate"}} +``` + +Templates are limited to one argument. The `args` function can be used to wrap multiple arguments. + +```go +{{define "myMultiArgTemplate"}} + First argument: {{.arg0}} + Second argument: {{.arg1}} +{{end}} +{{template "myMultiArgTemplate" (args 1 2)}} +``` diff --git a/docs/configuration/template_reference.md b/docs/configuration/template_reference.md new file mode 100644 index 0000000000..dabea627f1 --- /dev/null +++ b/docs/configuration/template_reference.md @@ -0,0 +1,114 @@ +--- +title: Template reference +sort_rank: 5 +--- + +# Template reference + +Prometheus supports templating in the summary and description fields of +alerts, as well as in served console pages. Templates have the ability to run +queries against the local database, iterate over data, use conditionals, format +data, etc. The Prometheus templating language is based on the +[Go templating](http://golang.org/pkg/text/template/) system. + +## Data Structures + +The primary data structure for dealing with time series data is the sample, defined as: + +```go +type sample struct { + Labels map[string]string + Value float64 +} +``` + +The metric name of the sample is encoded in a special `__name__` label in the `Labels` map. + +`[]sample` means a list of samples. + +`interface{}` in Go is similar to a void pointer in C. + +## Functions + +In addition to the [default +functions](http://golang.org/pkg/text/template/#hdr-Functions) provided by Go +templating, Prometheus provides functions for easier processing of query +results in templates. + +If functions are used in a pipeline, the pipeline value is passed as the last argument. + +### Queries + +| Name | Arguments | Returns | Notes | +| ------------- | ------------- | -------- | -------- | +| query | query string | []sample | Queries the database, does not support returning range vectors. | +| first | []sample | sample | Equivalent to `index a 0` | +| label | label, sample | string | Equivalent to `index sample.Labels label` | +| value | sample | float64 | Equivalent to `sample.Value` | +| sortByLabel | label, []samples | []sample | Sorts the samples by the given label. Is stable. | + +`first`, `label` and `value` are intended to make query results easily usable in pipelines. + +### Numbers + +| Name | Arguments | Returns | Notes | +| ------------- | --------------| --------| --------- | +| humanize | number | string | Converts a number to a more readable format, using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix). +| humanize1024 | number | string | Like `humanize`, but uses 1024 as the base rather than 1000. | +| humanizeDuration | number | string | Converts a duration in seconds to a more readable format. | +| humanizeTimestamp | number | string | Converts a Unix timestamp in seconds to a more readable format. | + +Humanizing functions are intended to produce reasonable output for consumption +by humans, and are not guaranteed to return the same results between Prometheus +versions. + +### Strings + +| Name | Arguments | Returns | Notes | +| ------------- | ------------- | ------- | ----------- | +| title | string | string | [strings.Title](http://golang.org/pkg/strings/#Title), capitalises first character of each word.| +| toUpper | string | string | [strings.ToUpper](http://golang.org/pkg/strings/#ToUpper), converts all characters to upper case.| +| toLower | string | string | [strings.ToLower](http://golang.org/pkg/strings/#ToLower), converts all characters to lower case.| +| match | pattern, text | boolean | [regexp.MatchString](http://golang.org/pkg/regexp/#MatchString) Tests for a unanchored regexp match. | +| reReplaceAll | pattern, replacement, text | string | [Regexp.ReplaceAllString](http://golang.org/pkg/regexp/#Regexp.ReplaceAllString) Regexp substitution, unanchored. | +| graphLink | expr | string | Returns path to graph view in the [expression browser](https://prometheus.io/docs/visualization/browser/) for the expression. | +| tableLink | expr | string | Returns path to tabular ("Console") view in the [expression browser](https://prometheus.io/docs/visualization/browser/) for the expression. | + +### Others + +| Name | Arguments | Returns | Notes | +| ------------- | ------------- | ------- | ----------- | +| args | []interface{} | map[string]interface{} | This converts a list of objects to a map with keys arg0, arg1 etc. This is intended to allow multiple arguments to be passed to templates. | +| tmpl | string, []interface{} | nothing | Like the built-in `template`, but allows non-literals as the template name. Note that the result is assumed to be safe, and will not be auto-escaped. Only available in consoles. | +| safeHtml | string | string | Marks string as HTML not requiring auto-escaping. | + +## Template type differences + +Each of the types of templates provide different information that can be used to +parameterize templates, and have a few other differences. + +### Alert field templates + +`.Value` and `.Labels` contain the alert value and labels. They are also exposed +as the `$value` and `$labels` variables for convenience. + +### Console templates + +Consoles are exposed on `/consoles/`, and sourced from the directory pointed to +by the `-web.console.templates` flag. + +Console templates are rendered with +[html/template](http://golang.org/pkg/html/template/), which provides +auto-escaping. To bypass the auto-escaping use the `safe*` functions., + +URL parameters are available as a map in `.Params`. To access multiple URL +parameters by the same name, `.RawParams` is a map of the list values for each +parameter. The URL path is available in `.Path`, excluding the `/consoles/` +prefix. + +Consoles also have access to all the templates defined with `{{define +"templateName"}}...{{end}}` found in `*.lib` files in the directory pointed to +by the `-web.console.libraries` flag. As this is a shared namespace, take care +to avoid clashes with other users. Template names beginning with `prom`, +`_prom`, and `__` are reserved for use by Prometheus, as are the functions +listed above.