Merge pull request #131 from prometheus/docs-improvements

Docs improvements

content/docs/introduction/faq.md

@@ -117,11 +117,15 @@ for the current state of this effort.
 
 ### Which languages have instrumentation libraries?
 
-Currently, there are client libraries for:
+Currently, there are official client libraries for:
 
 * [Go](https://github.com/prometheus/client_golang)
-* [Java or Scala](https://github.com/prometheus/client_java)
+* [Java (JVM)](https://github.com/prometheus/client_java)
 * [Ruby](https://github.com/prometheus/client_ruby)
+* [Python](https://github.com/prometheus/client_python)
+
+There are also a number of independently maintained client libraries. See the
+[client libraries](/docs/instrumenting/clientlibs/) documentation.
 
 If you are interested in contributing a client library for a new language, see
 the [exposition formats](/docs/instrumenting/exposition_formats/).

content/docs/introduction/getting_started.md

@@ -21,28 +21,23 @@ git clone https://github.com/prometheus/prometheus.git
 
 ## Building Prometheus
 
-Building Prometheus currently still requires a `make` step, as some parts of
-the source are autogenerated (web assets).
+[Download the latest release](https://github.com/prometheus/prometheus/releases)
+of Prometheus for your platform, then extract and run it:
 
-```language-bash
-cd prometheus
-make build
+```
+tar xvfz prometheus-*.tar.gz
+./prometheus
 ```
 
-Note that building requires a fair amount of memory. You should have
-at least 2GiB of RAM available.
-
-If you encounter problems building Prometheus, see [the more detailed build
-instructions](https://github.com/prometheus/prometheus#use-make) in the
-README.md.
+It should fail to start, complaining about the absence of a configuration file.
 
 ## Configuring Prometheus to monitor itself
 
 Prometheus collects metrics from monitored targets by scraping metrics HTTP
 endpoints on these targets. Since Prometheus also exposes data in the same
-manner about itself, it may also be used to scrape and monitor its own health.
+manner about itself, it can also scrape and monitor its own health.
 
-While a Prometheus server which collects only data about itself is not very
+While a Prometheus server that collects only data about itself is not very
 useful in practice, it is a good starting example. Save the following basic
 Prometheus configuration as a file named `prometheus.yml`:
 
@@ -56,7 +51,7 @@ global:
   labels:
     monitor: 'codelab-monitor'
 
-# A scrape configuration containing exactly one endpoint to scrape: 
+# A scrape configuration containing exactly one endpoint to scrape:
 # Here it's Prometheus itself.
 scrape_configs:
   # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
@@ -86,11 +81,11 @@ Prometheus build directory and run:
 ```
 
 Prometheus should start up and it should show a status page about itself at
-http://localhost:9090. Give it a couple of seconds to start collecting data
-about itself from its own HTTP metrics endpoint.
+http://localhost:9090. Give it a couple of seconds to collect data about itself
+from its own HTTP metrics endpoint.
 
 You can also verify that Prometheus is serving metrics about itself by
-navigating to its metrics exposure endpoint: http://localhost:9090/metrics
+navigating to its metrics endpoint: http://localhost:9090/metrics
 
 By default, Prometheus will only execute at most one OS thread at a
 time. In production scenarios on multi-CPU machines, you will most
@@ -140,7 +135,7 @@ To count the number of returned time series, you could write:
 count(prometheus_target_interval_length_seconds)
 ```
 
-For further details about the expression language, see the
+For more about the expression language, see the
 [expression language documentation](/docs/querying/basics/).
 
 ## Using the graphing interface

content/docs/operating/storage.md

@@ -45,7 +45,7 @@ index via the following flags:
 
 Prometheus stores its on-disk time series data under the directory
 specified by the flag `storage.local.path`. The default path is
-`/tmp/metrics`, which is good to try something out quickly but most
+`./data`, which is good to try something out quickly but most
 likely not what you want for actual operations. The flag
 `storage.local.retention` allows you to configure the retention time
 for samples. Adjust it to your needs and your available disk space.
@@ -69,6 +69,13 @@ of thumb, keep it somewhere between 50% and 100% of the
 is larger checkpoints. The consequences of a value too low are much
 more serious.
 
+Out of the metrics that Prometheus exposes about itself, the following are
+particularly useful for tuning the flags above:
+
+* `prometheus_local_storage_memory_series`: The current number of series held in memory.
+* `prometheus_local_storage_memory_chunks`: The current number of chunks held in memory.
+* `prometheus_local_storage_chunks_to_persist`: The number of memory chunks that still need to be persisted to disk.
+
 ## Crash recovery
 
 Prometheus saves chunks to disk as soon as possible after they are

content/docs/querying/rules.md

@@ -17,14 +17,12 @@ process. The changes are only applied if all rule files are well-formatted.
 
 ## Syntax-checking rules
 To quickly check whether a rule file is syntactically correct without starting
-a Prometheus server, install and run Prometheus's `rule_checker` tool:
+a Prometheus server, install and run Prometheus's `promtool` command-line
+utility tool:
 
 ```bash
-# If $GOPATH/github.com/prometheus/prometheus already exists, update it first:
-go get -u github.com/prometheus/prometheus
-
-go install github.com/prometheus/prometheus/tools/rule_checker
-rule_checker /path/to/example.rules
+go get github.com/prometheus/prometheus/cmd/promtool
+promtool check-rules /path/to/example.rules
 ```
 
 When the file is syntactically valid, the checker prints a textual
@@ -54,7 +52,7 @@ Some examples:
     job:http_inprogress_requests:sum = sum(http_inprogress_requests) by (job)
 
     # Drop or rewrite labels in the result time series:
-    new_time series{label_to_change="new_value",label_to_drop=""} = old_time series
+    new_time_series{label_to_change="new_value",label_to_drop=""} = old_time_series
 
 Recording rules are evaluated at the interval specified by the
 `evaluation_interval` field in the Prometheus configuration. During each