Add/improve docs around honor_labels and conflict handling.

content/docs/concepts/jobs_instances.md

@@ -25,11 +25,10 @@ scraped time series which serve to identify the scraped target:
 * `job`: The configured job name that the target belongs to.
 * `instance`: The `<host>:<port>` part of the target's URL that was scraped.
 
-If either of these labels are already present in the scraped 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.
+If either of these labels are already present in the scraped data, the behavior
+depends on the `honor_labels` configuration option. See the
+[scrape configuration documentation](/docs/operating/configuration/#scrape-configurations-scrape_config)
+for more information.
 
 For each instance scrape, Prometheus stores a sample of the form
 `up{job="<job-name>", instance="<instance-id>"}` with a value of `1` if the

content/docs/operating/configuration.md

@@ -35,6 +35,7 @@ Generic placeholders are defined as follows:
 * `<labelname>`: a string matching the regular expression `[a-zA-Z_][a-zA-Z0-9_]*`
 * `<labelvalue>`: a string of unicode characters
 * `<filename>`: a valid path in the current working directory
+* `<boolean>`: a boolean that can take the values `true` or `false`
 
 The other placeholders are specified separately.
 
@@ -94,6 +95,21 @@ job_name: <name>
 # The HTTP resource path on which to fetch metrics from targets.
 [ metrics_path: <path> | default = /metrics ]
 
+# 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).
+#
+# 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.
+#
+# If honor_labels is set to "false", label conflicts are resolved by renaming
+# conflicting labels in the scraped data to "exported_<original-label>" (for
+# 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.
+[ honor_labels: <boolean> | default = false ]
+
 # The URL scheme with which to fetch metrics from targets.
 [ scheme: <scheme> | default = http ]