Merge pull request #33 from prometheus/release

Document new flag and add example

Makefile.COMMON

@@ -48,7 +48,7 @@ ifeq ($(GOOS),darwin)
 	RELEASE_SUFFIX ?= -osx$(shell sw_vers -productVersion)
 endif
 
-GO_VERSION ?= 1.4.2
+GO_VERSION ?= 1.5.1
 GOURL      ?= https://golang.org/dl
 GOPKG      ?= go$(GO_VERSION).$(GOOS)-$(GOARCH)$(RELEASE_SUFFIX).tar.gz
 GOPATH     := $(CURDIR)/.build/gopath

README.md

@@ -18,6 +18,7 @@ collect.auto_increment.columns             | Collect auto_increment columns and
 collect.info_schema.userstats              | If running with userstat=1, set to true to collect user statistics.
 collect.perf_schema.eventsstatements       | Collect time metrics from performance_schema.events_statements_summary_by_digest.
 collect.perf_schema.eventsstatements.limit | Limit the number of events statements digests by response time. (default: 250)
+collect.perf_schema.eventsstatements.digest_text_limit | Maximum length of the normalized statement text. (default: 120)
 collect.perf_schema.indexiowaits           | Collect metrics from performance_schema.table_io_waits_summary_by_index_usage.
 collect.perf_schema.indexiowaitstime       | Collect time metrics from performance_schema.table_io_waits_summary_by_index_usage.
 collect.perf_schema.tableiowaits           | Collect metrics from performance_schema.table_io_waits_summary_by_table.
@@ -44,3 +45,27 @@ docker pull prom/mysqld-exporter
 docker run -d -p 9104:9104 --link=my_mysql_container:bdd  \
         -e DATA_SOURCE_NAME="user:password@(bdd:3306)/database" prom/mysqld-exporter
 ```
+
+## Example queries
+
+Certain queries to `events_statements` metrics will contain a query digest
+label in the result vector. The `events_statements_digest_text` metrics
+stores a mapping of those digests to their actual query template (digest_text).
+This metric can be used to join in the digest text to a query result so it can
+be interpreted in a more meaningful way.
+
+Suppose a query is:
+
+    sum(rate(mysql_perf_schema_events_statements_total[5m])) by (digest)
+
+The result vector contains the rate of events per digest, which is of little
+meaning without knowing the actual query behind the digest.
+
+Extending the query adds a `digest_text` label to the result vector showing us
+exactly that information:
+
+    (sum(rate(mysql_perf_schema_events_statements_total[5m])) by (digest)) * on(digest) group_right(schema, digest_text) mysql_perf_schema_events_statements_digest_text
+
+This extension (`* on(digest)...`) is generally applicable to all similar
+queries.
+