Merge pull request #151 from prometheus/federation

Document federation use cases and configuration.

content/docs/operating/configuration.md

 ---
 title: Configuration
 nav_icon: sliders
+sort_rank: 1
 ---
 
 # Configuration

content/docs/operating/federation.md

+---
+title: Federation
+sort_rank: 3
+---
+
+# Federation
+
+Federation allows a Prometheus server to scrape selected time series from
+another Prometheus server.
+
+## Use cases
+
+There are different use cases for federation. Commonly, it is used to either
+achieve scalable Prometheus monitoring setups or to pull related metrics from
+one service's Prometheus into another.
+
+### Hierarchical federation
+
+Hierarchical federation allows Prometheus to scale to environments with tens of
+data centers and millions of nodes. In this use case, the federation topology
+resembles a tree, with higher-level Prometheus servers collecting aggregated
+time series data from a larger number of subordinated servers.
+
+For example, a setup might consist of many per-datacenter Prometheus servers
+that collect data in high detail (instance-level drill-down), and a set of
+global Prometheus servers which collect and store only aggregated data
+(job-level drill-down) from those local servers. This provides an aggregate
+global view and detailed local views.
+
+### Cross-service federation
+
+In cross-service federation, a Prometheus server of one service is configured
+to scrape selected data from another service's Prometheus server to enable
+alerting and queries against both datasets within a single server.
+
+For example, a cluster scheduler running multiple services might expose
+resource usage information (like memory and CPU usage) about service instances
+running on the cluster. On the other hand, a service running on that cluster
+will only expose application-specific service metrics. Often, these two sets of
+metrics are scraped by separate Prometheus servers. Using federation, the
+Prometheus server containing service-level metrics may pull in the cluster
+resource usage metrics about its specific service from the cluster Prometheus,
+so that both sets of metrics can be used within that server.
+
+## Configuring federation
+
+On any given Prometheus server, the `/federate` endpoint allows retrieving the
+current value for a selected set of time series in that server. At least one
+`match[]` URL parameter must be specified to select the series to expose. Each
+`match[]` argument needs to specify an
+[instant vector selector](/docs/querying/basics/#instant-vector-selectors) like
+`up` or `{job="api-server"}`. If multiple `match[]` parameters are provided,
+the union of all matched series is selected.
+
+To federate metrics from one server to another, configure your destination
+Prometheus server to scrape from the `/federate` endpoint of a source server,
+while also enabling the `honor_labels` scrape option (to not overwrite any
+labels exposed by the source server) and passing in the desired `match[]`
+parameters. For example, the following `scrape_config` federates any series
+with the label `job="prometheus"` or a metric name starting with `job:` from
+the Prometheus servers at `source-prometheus-{1,2,3}:9090` into the scraping
+Prometheus:
+
+```
+- job_name: 'federate'
+  scrape_interval: 15s
+
+  honor_labels: true
+  metrics_path: '/federate'
+
+  params:
+    'match[]':
+      - 'job="prometheus"'
+      - '{__name__=~"^job:"}']
+
+  target_groups:
+    - targets:
+      - 'source-prometheus-1:9090'
+      - 'source-prometheus-2:9090'
+      - 'source-prometheus-3:9090'
+```

content/docs/operating/storage.md

 ---
 title: Storage
 nav_icon: database
+sort_rank: 2
 ---
 
 # Storage