Merge pull request #36 from prometheus/annotations-documentation

add annotations documentation.

.gitignore

@@ -8,3 +8,6 @@ tmp/
 
 # Crash Log
 crash.log
+
+# OS X file
+static/.DS_Store

content/docs/visualization/promdash.md

@@ -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
@@ -234,6 +303,5 @@ saved server-side.
 
 Add documention about:
 
-* annotation tags
 * `fullscreen` / `fullscreenTitle` URL parameters
 * document the dashboard JSON format