More docs vetting and completion.

content/docs/concepts/automatic.md

@@ -8,19 +8,21 @@ sort_rank: 3
 ## Automatically attached labels
 
 When Prometheus scrapes a target, it attaches some labels automatically to the
-scraped metrics time series which serve to identify the scraped target:
+scraped time series which serve to identify the scraped target:
 
-* `job`: The configured Prometheus job name for which the target was scraped.
-* `instance`: The specific URL of the instance's endpoint that was scraped.
+* `job`: The configured job name that the target belongs to.
+* `instance`: The URL of the target's endpoint that was scraped.
 
-If either of these labels are already present in the scraped data, they are not
-replaced. Instead, Prometheus adds its own labels with `exporter_` prepended to
-the label name: `exporter_job` and `exporter_instance`. The same pattern holds
-true for any manually supplied base labels supplied for a target group.
+If either of these labels are already present in the client-exposed data,
+Prometheus does not replace their values. Instead, it adds new labels with an
+`exporter_` prefix prepended to the label name: `exporter_job` and
+`exporter_instance`. The same pattern holds true for any labels that have been
+manually configured for a target group. This enables intermediary exporters to
+proxy metrics.
 
 ## Synthetic time series
-Prometheus also generates some time series internally which are not directly
-taken from the scraped data:
+Prometheus also generates and stores some time series automatically which are
+not directly derived from scraped data:
 
-* `up`: for each endpoint scrape, a sample of the form `up{job="...", instance="..."}` is stored, with a value of `1.0` indicating that the target was successfully scraped (it is up) and `0.0` indicating that the endpoint is down.
-* `ALERTS`: for pending and firing alerts, a time series of the form `ALERTS{alertname="...", alertstate="pending|firing",...alertlabels...}` is written out. The sample value is 1.0 as long as the alert is in the indicated active (pending/firing) state, but a single 0.0 value gets written out when an alert transitions from active to inactive state.
+* `up`: for each endpoint scrape, a sample of the form `up{job="...", instance="..."}` is stored, with a value of `1` indicating that the target was successfully scraped (it is up) and `0` indicating that the endpoint is down.
+* `ALERTS`: for pending and firing alerts, a time series of the form `ALERTS{alertname="...", alertstate="pending|firing",...alertlabels...}` is written out. The sample value is `1` as long as the alert is in the indicated active (pending/firing) state, but a single `0` value gets written out when an alert transitions from active to inactive state.

content/docs/concepts/metric_types.md

@@ -11,9 +11,6 @@ Prometheus offers three core metric types:
   * Gauges
   * Summaries
 
-Each type is useful for a different purpose, so it is important to use the
-right one for the right job.
-
 Metric types are currently only differentiated in the client libraries (to
 enable APIs tailored to the usage of the specific types) and in the wire
 protocol. The Prometheus server does not yet make use of the type information
@@ -22,14 +19,12 @@ after ingesting samples as time series. This may change in the future.
 ## Counter
 
 A _counter_ is a cumulative metric that represents a single numerical value
-that only ever goes up. That implies that it cannot be used to count items
-whose number can also go down, e.g. the number of currently running goroutines.
-Those "counts" are represented by gauges.
-
-A counter is typically used to count requests served, tasks completed, errors
-occurred, etc.
+that only ever goes up. A counter is typically used to count requests served,
+tasks completed, errors occurred, etc. Counters should not be used to expose
+current counts of items whose number can also go down, e.g. the number of
+currently running goroutines. Use gauges for this use case.
 
-Client library usage documentation for counters:
+See the client library usage documentation for counters:
 
    * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Counter)
    * [Java](https://github.com/prometheus/client_java/blob/master/client/src/main/java/io/prometheus/client/metrics/Counter.java)
@@ -45,7 +40,7 @@ Gauges are typically used for measured values like temperatures or current
 memory usage, but also "counts" that can go up and down, like the number of
 running goroutines.
 
-Client library usage documentation for gauges:
+See the client library usage documentation for gauges:
 
    * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Gauge)
    * [Java](https://github.com/prometheus/client_java/blob/master/client/src/main/java/io/prometheus/client/metrics/Gauge.java)
@@ -58,7 +53,7 @@ A _summary_ samples observations (usually things like request durations) over
 sliding windows of time and provides instantaneous insight into their
 distributions, frequencies, and sums.
 
-A summary reports the following information:
+A summary with a base metric name of `<basename>` exposes multiple time series:
 
   * streaming **quantile values** of observed events, exposed as `<basename>{quantile="<quantile label>"}`
   * the **total sum** of all observed values, exposed as `<basename>_sum`
@@ -70,7 +65,7 @@ with one metric.
 
 A typical use-case is the observation of request latencies or response sizes.
 
-Client library usage documentation for summaries:
+See the client library usage documentation for summaries:
 
    * [Go](http://godoc.org/github.com/prometheus/client_golang/prometheus#Summary)
    * [Java](https://github.com/prometheus/client_java/blob/master/client/src/main/java/io/prometheus/client/metrics/Summary.java)

content/docs/concepts/time_series.md

@@ -5,25 +5,41 @@ sort_rank: 1
 
 # Time series
 
-Prometheus fundamentally stores all data as
-[time series](http://en.wikipedia.org/wiki/Time_series): series of
-timestamp values.
+Prometheus fundamentally stores all data as [_time
+series_](http://en.wikipedia.org/wiki/Time_series): streams of timestamped
+values belonging to the same metric and the same set of labeled dimensions.
+Besides stored timeseries, Prometheus may generate temporary derived timeseries
+as the result of queries.
 
 ## Identification
-Time series are uniquely identified by a _metric name_ and a set of _key-value
-pairs_, also known as labels. Changing any label value, including adding or
-removing a label, will result in a new time series.
+Every time series is uniquely identified by its _metric name_ and a set of
+_key-value pairs_, also known as _labels_. Changing any label value, including
+adding or removing a label, will result in a new time series.
 
-Metric names must match the regular expression `[a-zA-Z_:][a-zA-Z0-9_:]`.
+Labels enable Prometheus's highly-dimensional data model: any given combination
+of labels for the same metric name identifies a particular dimensional
+instantiation of that metric (for example: all HTTP requests that used the
+method `POST` and which resulted in a `404` response).
+
+Metric names may contain ASCII letters, numbers, as well as underscores and
+colons. They must match the regex `[a-zA-Z_:][a-zA-Z0-9_:]`.
+
+Label names may contain ASCII letters, numbers, as well as underscores. They
+must match the regex `[a-zA-Z_][a-zA-Z0-9_]`.
+
+Label values may contain any Unicode characters.
+
+See also the [best practices for naming metrics and labels](/docs/practices/naming).
 
 ## Samples
-Samples form the actual data that time series consist of. A sample consists of:
+Samples form the actual time series data. Each sample consists of:
 
-   * a value with float64-precision
-   * a timestamp with millisecond-precision
+   * a float64 value
+   * a millisecond-precision timestamp
 
 ## Notation
-Given a metric name and a set of labels, we frequently identify time series using this notation:
+Given a metric name and a set of labels, time series are frequently identified
+using this notation:
 
     <metric name>{<label name>=<label value>, ...}
 
@@ -32,3 +48,5 @@ the labels `method="POST"` and `handler="/messages"` could be written like
 this:
 
     api_http_requests_total{method="POST", handler="/messages"}
+
+This is the same notation that [OpenTSDB](http://opentsdb.net/) uses.

content/docs/querying/basics.md

@@ -5,12 +5,10 @@ sort_rank: 1
 
 # Querying Prometheus
 
-## Overview
-
 Prometheus provides a functional expression language that lets the user select
-and aggregate time series data in real-time. The result of an expression can
-either be shown as a graph, viewed as data in the expression browser, or
-consumed and further processed by external systems via the HTTP API.
+and aggregate time series data in real time. The result of an expression can
+either be shown as a graph, viewed as tabular data in Prometheus's expression
+browser, or consumed by external systems via the HTTP API.
 
 ## Examples
 
@@ -136,7 +134,7 @@ a `job` label set to `prometheus`:
 ## Operators
 
 Prometheus supports many binary and aggregation operators. These are described
-in detail in the [[Expression Language Operators]] page.
+in detail in the [[Expression Language Operators] page.
 
 ## Functions
 

content/docs/querying/functions.md

@@ -5,19 +5,19 @@ sort_rank: 3
 
 # Functions
 
-## abs()
+## `abs()`
 
 `abs(v vector)` returns the input vector with all sample values converted to
 their absolute value.
 
-## count_scalar()
+## `count_scalar()`
 
 `count_scalar(v instant-vector)` returns the number of elements in a time series
 vector as a scalar. This is in contrast to the `count()` aggregation operator,
 which always returns a vector (an empty one if the input vector is empty) and
 allows grouping by labels via a `by` clause.
 
-## delta()
+## `delta()`
 
 `delta(v range-vector, counter bool)` calculates the difference between the
 first and last value of each time series element in a range vector `v`,
@@ -41,12 +41,12 @@ ago:
 delta(cpu_temp_celsius{host="zeus"}[2h], 0)
 ```
 
-## drop_common_labels()
+## `drop_common_labels()`
 
 `drop_common_labels(instant-vector)` drops all labels that have the same name
 and value across all series in the input vector.
 
-## rate()
+## `rate()`
 
 `rate(v range-vector)` behaves like `delta()`, with two differences:
 * the returned delta is converted into a per-second rate, according to the respective interval
@@ -59,28 +59,28 @@ over the last 5 minutes, per time series in the range vector:
 rate(http_requests{job="api-server"}[5m])
 ```
 
-## scalar()
+## `scalar()`
 
 Given a single-element input vector, `scalar(v instant-vector)` returns the
 sample value of that single element as a scalar. If the input vector doesn't
 have exactly one element, `scalar` will return `NaN`.
 
-## sort()
+## `sort()`
 
 `sort(v instant-vector)` returns vector elements sorted by their sample values,
 in ascending order.
 
-## sort_desc()
+## `sort_desc()`
 
 Same as `sort`, but sorts in descending order.
 
-## time()
+## `time()`
 
 `time()` returns the number of seconds since January 1, 1970 UTC. Note that
 this doesn't actually return the current time, but the time at which the
 expression is to be evaluated.
 
-## *_over_time(): Aggregating values within series over time:
+## `<aggregation>_over_time()`: Aggregating values over time:
 
 The following functions allow aggregating each series of a given range vector
 over time and return an instant vector with per-series aggregation results:
@@ -91,7 +91,7 @@ over time and return an instant vector with per-series aggregation results:
 - `sum_over_time(range-vector)`: the sum of all values under the specified interval.
 - `count_over_time(range-vector)`: the count of all values under the specified interval.
 
-## topk() / bottomk()
+## `topk()` and `bottomk()`
 
 `topk(k integer, v instant-vector)` returns the `k` largest elements of `v` by
 sample value.

static/docs.css

@@ -96,6 +96,11 @@ footer p {
   font-size: 25px;
 }
 
+.doc-content > h2 code {
+  color: #e6522c;
+  background: none;
+}
+
 pre {
   font-family: "Courier New", Monaco, Menlo, Consolas, monospace;
   background-color: #444;