docs: remove recommendation for prometheus metric_version=2 (#11158)

plugins/inputs/prometheus/README.md

@@ -11,13 +11,9 @@ in Prometheus format.
   ## An array of urls to scrape metrics from.
   urls = ["http://localhost:9100/metrics"]
   
-  ## Metric version controls the mapping from Prometheus metrics into
-  ## Telegraf metrics.  When using the prometheus_client output, use the same
-  ## value in both plugins to ensure metrics are round-tripped without
-  ## modification.
-  ##
-  ##   example: metric_version = 1; 
-  ##            metric_version = 2; recommended version
+  ## Metric version controls the mapping from Prometheus metrics into Telegraf metrics.
+  ## See "Metric Format Configuration" in plugins/inputs/prometheus/README.md for details.
+  ## Valid options: 1, 2
   # metric_version = 1
   
   ## Url tag name (tag containing scrapped url. optional, default is "url")
@@ -104,6 +100,35 @@ in Prometheus format.
 
 `urls` can contain a unix socket as well. If a different path is required (default is `/metrics` for both http[s] and unix) for a unix socket, add `path` as a query parameter as follows: `unix:///var/run/prometheus.sock?path=/custom/metrics`
 
+### Metric Format Configuration
+
+The `metric_version` setting controls how telegraf translates prometheus format
+metrics to telegraf metrics. There are two options.
+
+With `metric_version = 1`, the prometheus metric name becomes the telegraf
+metric name. Prometheus labels become telegraf tags. Prometheus values become
+telegraf field values. The fields have generic keys based on the type of the
+prometheus metric. This option produces metrics that are dense (not
+sparse). Denseness is a useful property for some outputs, including those that
+are more efficient with row-oriented data.
+
+`metric_version = 2` differs in a few ways. The prometheus metric name becomes a
+telegraf field key. Metrics hold more than one value and the field keys aren't
+generic. The resulting metrics are sparse, but for some outputs they may be
+easier to process or query, including those that are more efficient with
+column-oriented data. The telegraf metric name is the same for all metrics in
+the input instance. It can be set with the `name_override` setting and defaults
+to "prometheus". To have multiple metric names, you can use multiple instances
+of the plugin, each with its own `name_override`.
+
+`metric_version = 2` uses the same histogram format as the [histogram
+aggregator](../../aggregators/histogram/README.md)
+
+The Example Outputs sections shows examples for both options.
+
+When using this plugin along with the prometheus_client output, use the same
+option in both to ensure metrics are round-tripped without modification.
+
 ### Kubernetes Service Discovery
 
 URLs listed in the `kubernetes_services` parameter will be expanded

plugins/outputs/prometheus_client/README.md

@@ -11,12 +11,9 @@ metrics on `/metrics` (default) to be polled by a Prometheus server.
   ## Address to listen on.
   listen = ":9273"
 
-  ## Metric version controls the mapping from Telegraf metrics into
-  ## Prometheus format.  When using the prometheus input, use the same value in
-  ## both plugins to ensure metrics are round-tripped without modification.
-  ##
-  ##   example: metric_version = 1;
-  ##            metric_version = 2; recommended version
+  ## Metric version controls the mapping from Prometheus metrics into Telegraf metrics.
+  ## See "Metric Format Configuration" in plugins/inputs/prometheus/README.md for details.
+  ## Valid options: 1, 2
   # metric_version = 1
 
   ## Use HTTP Basic Authentication.