Skip to content

D
docs
Commit ff7a327f authored by Brian Brazil's avatar Brian Brazil
Browse files
Options

Expand console template docs. 

Explain the general structure, prom_query_drilldown and graph library.
parent c5234641
Hide whitespace changes
Inline Side-by-side
Showing with 144 additions and 13 deletions
content/docs/visualization/consoles.md
View file @ ff7a327f
......@@ -5,19 +5,22 @@ sort_rank: 3
# Console templates
The Console templates allow for creation of arbitrary consoles using the [Go
templating langauge](http://golang.org/pkg/text/template/). These are served
Console templates allow for creation of arbitrary consoles using the [Go
templating language](http://golang.org/pkg/text/template/). These are served
from the Prometheus server.
Console templates are the most powerful way to create templates that can be easily managed in source control, there is a learning curve though so
users new to this style of monitoring should try out [PromDash](../promdash/) first.
Console templates are the most powerful way to create templates that can be
easily managed in source control. There is a learning curve though, so users new
to this style of monitoring should try out [PromDash](../promdash/) first.
## Getting started
Prometheus comes with an example set of consoles to get you going, these can be found at `/consoles/index.html.example` on a running Prometheus
and will let you see Node Exporter consoles if your node exporters have a `job="node"` label.
Prometheus comes with an example set of consoles to get you going. These can be
found at `/consoles/index.html.example` on a running Prometheus and will
display Node Exporter consoles if Prometheus is scraping Node Exporters with a
`job="node"` label.
Consoles have 5 parts:
The example consoles have 5 parts:
1. A navigation bar on top
1. A menu on the left
......@@ -25,15 +28,143 @@ Consoles have 5 parts:
1. The main content in the center, usually graphs
1. A table on the right
The navigation bar is for links to other systems, such as other Prometheuses, documentation and whatever else makes sense to you.
The menu is for navigation inside the Prometheus, it's very useful to be able to quickly open a console in another tab to correlate information.
Both are configured in `console_libraries/menu.lib`.
The navigation bar is for links to other systems, such as other Prometheuses,
documentation, and whatever else makes sense to you. The menu is for navigation
inside the same Prometheus server, which is very useful to be able to quickly
open a console in another tab to correlate information. Both are configured in
`console_libraries/menu.lib`.
The time controls allow changing of the duration and range of the graphs. Console URLs can be shared with others, they'll see the same graphs.
The time controls allow changing of the duration and range of the graphs.
Console URLs can be shared and will show the same graphs for others.
The main content is usually graphs. There's a configurable Javascript graphing
library provided that'll handle requesting data from Prometheus, and rendering
The main content is usually graphs. There is a configurable JavaScript graphing
library provided that will handle requesting data from Prometheus, and rendering
it via [Rickshaw](http://code.shutterstock.com/rickshaw/).
Finally, the table on the right can be used to display statistics in a more
compact form than graphs.
## Example Console
This is a basic console. It shows the number of tasks, how many of them are up,
the average CPU usage, and the average memory usage in the right-hand-side
table. The main content has a queries-per-second graph.
```
{{template "head" .}}
{{template "prom_right_table_head"}}
<tr>
<th>MyJob</th>
<th>{{ template "prom_query_drilldown" (args "sum(up{job='myjob'})") }}
/ {{ template "prom_query_drilldown" (args "count(up{job='myjob'})") }}
</th>
</tr>
<tr>
<td>CPU</td>
<td>{{ template "prom_query_drilldown" (args
"avg by(job)(rate(process_cpu_seconds_total{job='myjob'}[5m]))"
"s/s" "humanizeNoSmallPrefix") }}
</td>
</tr>
<tr>
<td>Memory</td>
<td>{{ template "prom_query_drilldown" (args
"avg by(job)(process_resident_memory_bytes{job='myjob'})"
"B" "humanize1024") }}
</td>
</tr>
{{template "prom_right_table_tail"}}
{{template "prom_content_head" .}}
<h1>MyJob</h1>
<h3>Queries</h3>
<div id="queryGraph"></div>
<script>
new PromConsole.Graph({
node: document.querySelector("#queryGraph"),
expr: "sum(rate(http_query_count{job='myjob'}[5m]))",
name: "Queries",
yAxisFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
yHoverFormatter: PromConsole.NumberFormatter.humanizeNoSmallPrefix,
yUnits: "/s",
yTitle: "Queries"
})
</script>
{{template "prom_content_tail" .}}
{{template "tail"}}
```
The `prom_right_table_head` and `prom_right_table_tail` templates contain the
right-hand-side table. This is optional.
`prom_query_drilldown` is a template that will evaluate the expression passed to it, format it,
and link to the expression in the [expression browser](../browser). The first
argument is the expression. The second argument is the unit to use. The third
argument is how to format the output. Only the first argument is requred.
Valid output formats for the third argument to `prom_query_drilldown`:
* Not specified: Default Go display output.
* `humanize`: Display the result using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
* `humanizeNoSmallPrefix`: For absolute values greater than 1, display the
result using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix). For
absolute values less than 1, display 3 significant digits. This is useful
to avoid units such as milliqueries per second that can be produced by
`humanize`.
* `humanize1024`: Display the humanized result using a base of 1024 rather than 1000.
This is usually used with `B` as the second argument to produce units such as `KiB` and `MiB`.
* `printf.3g`: Display 3 significant digits.
Custom formats can be defined. See
[prom.lib](https://github.com/prometheus/prometheus/blob/master/console_libraries/prom.lib) for examples.
## Graph Library
The graph library is invoked as:
```
<div id="queryGraph"></div>
<script>
new PromConsole.Graph({
node: document.querySelector("#queryGraph"),
expr: "sum(rate(http_query_count{job='myjob'}[5m]))"
})
</script>
```
The `head` template loads the required Javascript and CSS.
Parameters to the graph library:
| Name | Description
| ------------- | -------------
| expr | Required. Expression to graph.
| node | Required. DOM node to render into.
| duration | Optional. Duration of the graph. Defaults to 1 hour.
| endTime | Optional. Unixtime the graph ends at. Defaults to now.
| width | Optional. Width of the graph, excluding titles. Defaults to auto-detection.
| height | Optional. Height of the graph, excluding titles and legends. Defaults to 200 pixels.
| min | Optional. Minimum x-axis value. Defaults to lowest data value.
| max | Optional. Maximum y-axis value. Defaults to highest data value.
| renderer | Optional. Type of graph. Options are `line` and `area` (stacked graph). Defaults to `line`.
| name | Optional. Title of plots in legend and hover detail. If passed a string, `[[ label ]]` will be substituted with the label value. If passed a function, it will be passed a map of labels and should return the name as a string.
| xTitle | Optional. Title of the x-axis. Defaults to `Time`.
| yUnits | Optional. Units of the y-axis. Defaults to empty.
| yTitle | Optional. Title of the y-axis. Defaults to empty.
| yAxisFormatter | Optional. Number formatter for the y-axis. Defaults to `PromConsole.NumberFormatter.humanize`.
| yHoverFormatter | Optional. Number formatter for the hover detail. Defaults to `PromConsole.NumberFormatter.humanizeExact`.
Valid options for the `yAxisFormatter` and `yHoverFormatter`:
* `PromConsole.NumberFormatter.humanize`: Format using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
* `PromConsole.NumberFormatter.humanizeNoSmallPrefix`: For absolute values
greater than 1, format using using [metric prefixes](http://en.wikipedia.org/wiki/Metric_prefix).
For absolute values less than 1, format with 3 significant digits. This is
useful to avoid units such as milliqueries per second that can be produced by
`PromConsole.NumberFormatter.humanize`.
* `PromConsole.NumberFormatter.humanize1024`: Format the humanized result using a base of 1024 rather than 1000.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment

Technounit-GROUP 2023