mirror of
https://github.com/prometheus/prometheus.git
synced 2025-02-02 08:31:11 -08:00
Import template reference and examples
This commit is contained in:
Tobias Schmidt
parent
f432b8176d
commit
f49ae044d7
116
docs/configuration/template_examples.md
Normal file
116
docs/configuration/template_examples.md
Normal file
|
|
@ -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
|
||||||
|
<table>
|
||||||
|
{{ range printf "node_network_receive_bytes{job='node',instance='%s',device!='lo'}" .Params.instance | query | sortByLabel "device"}}
|
||||||
|
<tr><th colspan=2>{{ .Labels.device }}</th></tr>
|
||||||
|
<tr>
|
||||||
|
<td>Received</td>
|
||||||
|
<td>{{ 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}}</td>
|
||||||
|
</tr>
|
||||||
|
<tr>
|
||||||
|
<td>Transmitted</td>
|
||||||
|
<td>{{ 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}}</td>
|
||||||
|
</tr>{{ end }}
|
||||||
|
<table>
|
||||||
|
```
|
||||||
|
|
||||||
|
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)}}
|
||||||
|
```
|
||||||
114
docs/configuration/template_reference.md
Normal file
114
docs/configuration/template_reference.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in a new issue