Skip to content

Commit

Permalink
docs: remove recommendation for prometheus metric_version=2 (#11158)
Browse files Browse the repository at this point in the history
  • Loading branch information
reimda authored and MyaLongmire committed Jul 6, 2022
1 parent 1f8414d commit f09d4e3
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 13 deletions.
39 changes: 32 additions & 7 deletions plugins/inputs/prometheus/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand Down Expand Up @@ -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
Expand Down
9 changes: 3 additions & 6 deletions plugins/outputs/prometheus_client/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down

0 comments on commit f09d4e3

Please sign in to comment.