Merge pull request #220 from prometheus/external-labels

Document new name and semantics of external labels.

content/docs/introduction/getting_started.md

@@ -39,8 +39,9 @@ global:
   evaluation_interval: 15s # By default, scrape targets every 15 seconds.
   # scrape_timeout is set to the global default (10s).
 
-  # Attach these extra labels to all timeseries collected by this Prometheus instance.
-  labels:
+  # Attach these labels to any time series or alerts when communicating with
+  # external systems (federation, remote storage, Alertmanager).
+  external_labels:
     monitor: 'codelab-monitor'
 
 # A scrape configuration containing exactly one endpoint to scrape:

content/docs/operating/configuration.md

@@ -57,8 +57,9 @@ global:
   # How frequently to evaluate rules by default.
   [ evaluation_interval: <duration> | default = 1m ]
 
-  # The labels to add to any timeseries that this Prometheus instance scrapes.
-  labels:
+  # The labels to add to any time series or alerts when communicating with
+  # external systems (federation, remote storage, Alertmanager).
+  external_labels:
     [ <labelname>: <labelvalue> ... ]
 
 # Rule files specifies a list of files from which rules are read.
@@ -112,8 +113,8 @@ job_name: <name>
 
 # honor_labels controls how Prometheus handles conflicts between labels that are
 # already present in scraped data and labels that Prometheus would attach
-# server-side ("job" and "instance" labels, global labels, manually configured
-# target labels, and labels generated by service discovery implementations).
+# server-side ("job" and "instance" labels, manually configured target
+# labels, and labels generated by service discovery implementations).
 #
 # If honor_labels is set to "true", label conflicts are resolved by keeping label
 # values from the scraped data and ignoring the conflicting server-side labels.
@@ -123,6 +124,10 @@ job_name: <name>
 # example "exported_instance", "exported_job") and then attaching server-side
 # labels. This is useful for use cases such as federation, where all labels
 # specified in the target should be preserved.
+#
+# Note that any globally configured "external_labels" are unaffected by this
+# setting. In communication with external systems, they are always applied only
+# when a time series does not have a given label yet and are ignored otherwise.
 [ honor_labels: <boolean> | default = false ]
 
 # The URL scheme with which to fetch metrics from targets.
@@ -455,7 +460,7 @@ it gets scraped. Multiple relabeling steps can be configured per scrape configur
 They are applied to the label set of each target in order of their appearance
 in the configuration file.
 
-Initially, aside from the configured global and per-target labels, a target's `job`
+Initially, aside from the configured per-target labels, a target's `job`
 label is set to the `job_name` value of the respective scrape configuration.
 The `__address__` label is set to the `<host>:<port>` address of the target.
 After relabeling, the `instance` label is set to the value of `__address__` by default if