Skip to content

D
docs
Commit 29a1fbbd authored by Julius Volz's avatar Julius Volz
Browse files
Options

Reorganize sections and rework annotation docs.

parent a6c5677e
Hide whitespace changes
Inline Side-by-side
Showing with 126 additions and 111 deletions
content/docs/visualization/promdash.md
View file @ 29a1fbbd
......@@ -62,11 +62,11 @@ have an effect on the dashboard as a whole:
* **Resolution**: A slider that selects the resolution with which to load
data from Prometheus.
* **Show annotation tags**: Select whether to show the UI for editing tags
that speficy which annotations to load and display in graphs. See the
"Annotation tags" section.
that specify which annotations to load and display in graphs. See the
[Annotations](#annotations) section.
* **Show template variables**: Select whether to show the UI for editing
global template variables for the dashboard. See the "Template variables"
section for more information.
global template variables for the dashboard. See the [Using template
variables](#using-template-variables) section.
* **Encode entire dashboard in URL**: Select whether to continuously update the
browser URL as changes to the dashboard are made. The browser URL will then
always reflect the current contents and state of the dashboard and may be
......@@ -79,79 +79,41 @@ have an effect on the dashboard as a whole:
settings or the settings of individual widgets. Without saving, any changes
made to the dashboard are lost when reloading the page.
#### Using template variables
Template variables allow you to make generalized dashboards in which you set
only certain variables each time you display them. For example, if you were
interested in building a dashboard that shows statistics for a host, you
would not want to build a separate dashboard for each host. Instead, PromDash
lets you define the dashboard once and then create global template variables
for the changing parts of your dashboard. In the case of the host dashboard,
you might create a template variable called `host` and then let the user set
this variable to the name of the host which they are currently interested in.
The value of the variable value may then be inserted into relevant text input
fields in a widget's settings.
A variable is interpolated into a text input field by enclosing it with a set
of two curly braces: `{{variable-name}}`. The text inputs that support template
variable interpolation are:
* The widget title.
* The expression input fields in a Prometheus graph.
* The URL input of an iframe widget.
In the example of a host dashboard, we could interpolate the `host` variable
into each widget's Prometheus expressions, like:
cpu_time_ns{host="{{host}}"}
...and set the title to:
CPU time for {{host}} in nanoseconds
Besides creating and setting variables via the user interface, you may set
existing variables or even define new ones via the URL:
http://<promdash-url>/<dashboard-name>#!?var.<var1>=<val1>&var.<var2>=<val2>
In the example of the host dashboard, the URL could look like this:
http://promdash.somedomain.int/hoststats#!?var.host=myhost
### Configuring a Prometheus graph
## Adding Prometheus graphs
To add a Prometheus graph, click the "Add Graph" button on the dashboard.
To configure a Prometheus graph, move the mouse over its widget area until a
To configure the graph, move the mouse over its widget area until a
menu bar appears in the top left corner.
#### Datasources
To configure which data to display in a graph, select the `Datasources` menu
tab. It allows you to set one or multiple expressions to be graphed, along with
the Prometheus server they should be queried from. The supported expressions
are any standard
[Prometheus expression language expressions](https://github.com/prometheus/prometheus/wiki/Expression-Language).
### Datasources
To configure which data to display, select the `Datasources` menu tab. It
allows you to set one or multiple expressions to be graphed, along with the
Prometheus server they should be queried from. The supported expressions are
any standard [Prometheus expression language
expressions](https://github.com/prometheus/prometheus/wiki/Expression-Language).
For each expression, you can select a graph axis to map the resulting data on,
as well as a format string that specifies how the returned time series labels
should be reflected in the legend. See later sections on how to add axes and
format strings.
#### Time options
### Time options
The time options let you configure a custom range and time window per graph.
Note, however, that these are reset to the global time settings once the global
ones are changed again.
#### Graph and axis settings
### Graph and axis settings
The graph and axis settings allow you to configure a title for your graph, as
well as the preferred line interpolation and query resolution. Furthermore,
you may add a second axis and configure various options for each axis (stacked
vs. lines, axis scales, etc.).
#### Palette settings
### Palette settings
The palette settings allow you to select a color scheme for drawing the lines
and filled areas in graphs. If set, this overrides the global setting as long
as the global setting remains unchanged.
#### Legend settings
### Legend settings
The legend settings menu tab allows you to configure when to show the legend on
a graph, as well as defining how it should be formatted.
......@@ -167,20 +129,20 @@ interpolated version of the given format string. To reference specific label
values in the format string, use double curly braces: `{{label-name}}`. For
example: `{{host}} - cluster {{cluster}}`.
#### Link to graph
### Link to graph
The "Link to this graph" menu tab allows you to generate a link to a specific
graph. This link will show the graph in a single-widget fullscreen view as it
was configured when the link was generated. Subsequent changes to the
underlying graph will not affect the linked version of the graph.
### Using frames
## Adding inline frames
You can add arbitrary iframes as widgets to a PromDash dashboard by clicking
the "Add Frame" button. You will be prompted to enter a URL to display, which
may later be configured via the "Frame Source" menu tab. Similarly to
Prometheus graph widgets, frame widgets allow you to configure a title and
generate a link to the frame.
#### Automatic Graphite graph URL adjustment
### Automatic Graphite graph URL adjustment
PromDash has limited support for parsing and rewriting links to Graphite graph
URLs. If you want to embed a Graphite graph via a PromDash frame, enable the
option "this is a graphite graph" under the "Frame options" menu tab. PromDash
......@@ -188,6 +150,113 @@ will then automatically resize the Graphite graph to fit its widget by
dynamically rewriting the frame URL. It will also add time controls which act
similarly to those found in Prometheus graph widgets.
## Using template variables
Template variables allow you to make generalized dashboards in which you set
only certain variables each time you display them. For example, if you were
interested in building a dashboard that shows statistics for a host, you
would not want to build a separate dashboard for each host. Instead, PromDash
lets you define the dashboard once and then create global template variables
for the changing parts of your dashboard. In the case of the host dashboard,
you might create a template variable called `host` and then let the user set
this variable to the name of the host which they are currently interested in.
The value of the variable value may then be inserted into relevant text input
fields in a widget's settings.
A variable is interpolated into a text input field by enclosing it with a set
of two curly braces: `{{variable-name}}`. The text inputs that support template
variable interpolation are:
* The widget title.
* The expression input fields in a Prometheus graph.
* The URL input of an iframe widget.
* Annotation tag input fields.
In the example of a host dashboard, we could interpolate the `host` variable
into each widget's Prometheus expressions, like:
cpu_time_ns{host="{{host}}"}
...and set the title to:
CPU time for {{host}} in nanoseconds
Besides creating and setting variables via the user interface, you may set
existing variables or even define new ones via the URL:
http://<promdash-url>/<dashboard-name>#!?var.<var1>=<val1>&var.<var2>=<val2>
In the example of the host dashboard, the URL could look like this:
http://promdash.somedomain.int/hoststats#!?var.host=myhost
## Annotations
PromDash allows you to load timestamped annotations from an external service
and display them in graphs as vertical lines:
[![Annotation screenshot](/assets/annotations_example.png)](/assets/annotations_example.png)
### Configuring annotations
This section assumes that you already have a working annotation server. For
details on building one, see the [Annotations API](#annotations-api) section below.
The URL that PromDash should query for annotations is set
via the `ANNOTATIONS_URL` environment variable.
To enable annotations on a dashboard, first select "Display annotation tags" in
the global dashboard settings. Each input can hold an arbitrary number of
comma-separated tags that will be used to query your designated annotations
server. Once you have added your tags you can hide the annotation list by
un-checking annotations setting in the global dashboard settings.
Hovering over an annotation on a graph will display the annotation's message:
[![Annotation global config screenshot](/assets/annotations_hover.png)](/assets/annotations_hover.png)
### Annotations API
Although we do not distribute a publicly available annotations server yet, it
is easy to build one.
The URL from which PromDash fetches annotations has the following format:
${ANNOTATIONS_URL}?range=3600&tags[]=chef&tags[]=prometheus&until=1423491311.424
The parameters have the following meaning:
- `${ANNOTATIONS_URL}`: this is the configured `${ANNOTATIONS_URL}` environment
variable.
- `until`: This is the graph's end time as a Unix timestamp in seconds.
- `range`: This is the graph's range (stretching back from the end time) in seconds.
- `tags[]`: This is a list of the tags for which annotations should be loaded.
Each tag input on your dashboard represents a separate query. For example, if
you have three tag inputs, three requests will be made to your annotations
server.
The `until` and `range` parameters define the time window displayed by the
graph. Annotations that are returned to PromDash that do not fall within this
window will not be rendered.
The JSON payload returned from the annotations server needs to conform to this
schema:
```javascript
{
posts: [
{
created_at: 111232553, // UNIX timestamp
message: "annotation message here"
},
// ... more tags
]
}
```
All returned annotation tags will be rendered on every graph. There currently
is no support for rendering specific tags on only a subset of graphs.
## Embedding a dashboard
PromDash has support for embedding dashboards into other pages via iframes. To
get an embeddable view for a PromDash dashboard, add `embed` to the URL of a
......@@ -230,60 +299,6 @@ show `serverID` fields, and never `serverURL`, since any uploaded JSON
containing `serverURL`s is transformed immediately to `serverID`s before being
saved server-side.
### Annotation tags
Graph widgets have the ability to request annotations by `tagname` and then
render them on the graph. If you have a server running that stores events with
a timestamp, you can query it to render annotations on your widgets.
[![Annotation screenshot](/assets/annotations_example.png)](/assets/annotations_example.png)
To enable, first select "Display annotation tags" via the global dashboard
setting. Each input can hold an arbitrary number of comma-separated tags that
will be used to query your designated annotations server. Once you have added
your tags you can hide the annotation list by un-checking annotations setting
in the global dashboard settings.
The URL for your annotations server is set via the `ANNOTATIONS_URL`
environment variable when running PromDash.
When requesting annotations, the following query string parameters are sent to
the annotations server:
- `until`: This is the graph's endTime.
- `range`: This is the graph's range.
- `tags[]`: This is a list of the tags defined on your dashboard.
Each tag input on your dashboard represents a separate query. E.g., if you have
three tag inputs, three requests will be made to your annotations server, each
containing the tags from one input.
The `until` and `range` parameters define time window displayed by the graph.
Annotations that are returned to PromDash that do not fall within this window
will not be rendered.
The payload returned from the annotation server should conform to this schema:
```javascript
{
posts: [
{
created_at: 111232553, // UNIX timestamp
message: "annotation message here"
},
// ... more tags
]
}
```
All returned annotation tags will be rendered on every graph. There currently
is no support for rendering specific tags on only a subset of graphs.
Hovering over an annotation on a graph will display the annotation's message
(cf. schema above).
[![Annotation global config screenshot](/assets/annotations_hover.png)](/assets/annotations_hover.png)
## TODOs
Add documention about:
......
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