155 lines
7 KiB
Markdown
155 lines
7 KiB
Markdown
|
# OpenMetrics Format Parser Plugin
|
||
|
|
|
||
|
|
This plugin allows to parse the [OpenMetrics Text Format][] into Telegraf
|
||
|
|
metrics. It is used internally in [prometheus input](/plugins/inputs/prometheus)
|
||
|
|
but can also be used by e.g.
|
||
|
|
[http_listener_v2](/plugins/inputs/http_listener_v2) to simulate a Pushgateway.
|
||
|
|
|
||
|
|
The plugin allows to output different metric formats as described in the
|
||
|
|
[Metric Formats section](#metric-formats).
|
||
|
|
|
||
|
|
[OpenMetrics Text Format]: https://github.com/prometheus/OpenMetrics/blob/v1.0.0/specification/OpenMetrics.md
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
```toml
|
||
|
|
[[inputs.file]]
|
||
|
|
files = ["example"]
|
||
|
|
|
||
|
|
## Data format to consume.
|
||
|
|
## Each data format has its own unique set of configuration options, read
|
||
|
|
## more about them here:
|
||
|
|
## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
|
||
|
|
data_format = "openmetrics"
|
||
|
|
|
||
|
|
```
|
||
|
|
|
||
|
|
## Metric Formats
|
||
|
|
|
||
|
|
The metric_version setting controls how telegraf translates OpenMetrics'
|
||
|
|
metrics to Telegraf metrics. There are two options.
|
||
|
|
|
||
|
|
### `v1` format
|
||
|
|
|
||
|
|
In this version, the OpenMetrics metric-family name becomes the Telegraf metric
|
||
|
|
name, labels become tags and values become fields. The fields are named based
|
||
|
|
on the type of the OpenMetric metric. This option produces metrics that are
|
||
|
|
dense (contrary to the sparse metrics of`v2`).
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
```text
|
||
|
|
# TYPE acme_http_router_request_seconds summary
|
||
|
|
# UNIT acme_http_router_request_seconds seconds
|
||
|
|
# HELP acme_http_router_request_seconds Latency though all of ACME's HTTP request router.
|
||
|
|
acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32
|
||
|
|
acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.5"} 1.29854
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.9"} 54.85479
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.99"} 6884.32324
|
||
|
|
acme_http_router_request_seconds_created{path="/api/v1",method="GET"} 1605281325.0
|
||
|
|
acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3
|
||
|
|
acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0
|
||
|
|
acme_http_router_request_seconds_created{path="/api/v2",method="POST"} 1605281325.0
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.5"} 0.85412
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.9"} 1.15429
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.99"} 3698.48132
|
||
|
|
# TYPE go_goroutines gauge
|
||
|
|
# HELP go_goroutines Number of goroutines that currently exist.
|
||
|
|
go_goroutines 69
|
||
|
|
# TYPE process_cpu_seconds counter
|
||
|
|
# UNIT process_cpu_seconds seconds
|
||
|
|
# HELP process_cpu_seconds Total user and system CPU time spent in seconds.
|
||
|
|
process_cpu_seconds_total 4.20072246e+06
|
||
|
|
# EOF```
|
||
|
|
|
||
|
|
becomes
|
||
|
|
|
||
|
|
```text
|
||
|
|
acme_http_router_request_seconds,unit=seconds,path=/api/v1,method=GET sum=9036.32,count=807283.0,created=1605281325.0,0.5=1.29854,0.9=54.85479,0.99=6884.32324
|
||
|
|
acme_http_router_request_seconds,unit=seconds,path=/api/v2,method=POST sum=479.3,count=34.0,created=1605281325.0,0.5=0.85412,0.9=1.15429,0.99=3698.48132
|
||
|
|
go_goroutines gauge=69
|
||
|
|
process_cpu_seconds,unit=seconds counter=4200722.46
|
||
|
|
```
|
||
|
|
|
||
|
|
This is especially useful and efficient for outputs with row-oriented data
|
||
|
|
models.
|
||
|
|
|
||
|
|
### `v2` format
|
||
|
|
|
||
|
|
In this version, each OpenMetrics MetricPoint becomes a Telegraf metric with
|
||
|
|
a few exceptions for complex types like histograms. All Telegraf metrics are
|
||
|
|
named `prometheus` with OpenMetrics' labels become tags and the field-name is
|
||
|
|
based on the OpenMetrics metric-name.
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
Example:
|
||
|
|
|
||
|
|
```text
|
||
|
|
# TYPE acme_http_router_request_seconds summary
|
||
|
|
# UNIT acme_http_router_request_seconds seconds
|
||
|
|
# HELP acme_http_router_request_seconds Latency though all of ACME's HTTP request router.
|
||
|
|
acme_http_router_request_seconds_sum{path="/api/v1",method="GET"} 9036.32
|
||
|
|
acme_http_router_request_seconds_count{path="/api/v1",method="GET"} 807283.0
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.5"} 1.29854
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.9"} 54.85479
|
||
|
|
acme_http_router_request_seconds{path="/api/v1",method="GET",quantile="0.99"} 6884.32324
|
||
|
|
acme_http_router_request_seconds_created{path="/api/v1",method="GET"} 1605281325.0
|
||
|
|
acme_http_router_request_seconds_sum{path="/api/v2",method="POST"} 479.3
|
||
|
|
acme_http_router_request_seconds_count{path="/api/v2",method="POST"} 34.0
|
||
|
|
acme_http_router_request_seconds_created{path="/api/v2",method="POST"} 1605281325.0
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.5"} 0.85412
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.9"} 1.15429
|
||
|
|
acme_http_router_request_seconds{path="/api/v2",method="POST",quantile="0.99"} 3698.48132
|
||
|
|
# TYPE go_goroutines gauge
|
||
|
|
# HELP go_goroutines Number of goroutines that currently exist.
|
||
|
|
go_goroutines 69
|
||
|
|
# TYPE process_cpu_seconds counter
|
||
|
|
# UNIT process_cpu_seconds seconds
|
||
|
|
# HELP process_cpu_seconds Total user and system CPU time spent in seconds.
|
||
|
|
process_cpu_seconds_total 4.20072246e+06
|
||
|
|
# EOF```
|
||
|
|
|
||
|
|
becomes
|
||
|
|
|
||
|
|
```text
|
||
|
|
prometheus,method=GET,path=/api/v1,unit=seconds acme_http_router_request_seconds_count=807283,acme_http_router_request_seconds_created=1605281325,acme_http_router_request_seconds_sum=9036.32
|
||
|
|
prometheus,method=GET,path=/api/v1,quantile=0.5,unit=seconds acme_http_router_request_seconds=1.29854
|
||
|
|
prometheus,method=GET,path=/api/v1,quantile=0.9,unit=seconds acme_http_router_request_seconds=54.85479
|
||
|
|
prometheus,method=GET,path=/api/v1,quantile=0.99,unit=seconds acme_http_router_request_seconds=6884.32324
|
||
|
|
prometheus,method=POST,path=/api/v2,unit=seconds acme_http_router_request_seconds_count=34,acme_http_router_request_seconds_created=1605281325,acme_http_router_request_seconds_sum=479.3
|
||
|
|
prometheus,method=POST,path=/api/v2,quantile=0.5,unit=seconds acme_http_router_request_seconds=0.85412
|
||
|
|
prometheus,method=POST,path=/api/v2,quantile=0.9,unit=seconds acme_http_router_request_seconds=1.15429
|
||
|
|
prometheus,method=POST,path=/api/v2,quantile=0.99,unit=seconds acme_http_router_request_seconds=3698.48132
|
||
|
|
prometheus go_goroutines=69
|
||
|
|
prometheus,unit=seconds process_cpu_seconds=4200722.46
|
||
|
|
```
|
||
|
|
|
||
|
|
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
|
||
|
|
|
||
|
|
## Regenerating OpenMetrics code
|
||
|
|
|
||
|
|
Download the latest version of the protocol-buffer definition
|
||
|
|
|
||
|
|
```text
|
||
|
|
wget https://raw.githubusercontent.com/OpenObservability/OpenMetrics/main/proto/openmetrics_data_model.proto
|
||
|
|
```
|
||
|
|
|
||
|
|
and generate the go-code for the definition using
|
||
|
|
|
||
|
|
```text
|
||
|
|
protoc --proto_path=. \
|
||
|
|
--go_out=. \
|
||
|
|
--go_opt=paths=source_relative \
|
||
|
|
--go_opt=Mopenmetrics_data_model.proto=github.com/influxdata/telegraf/plugins/parsers/openmetrics \
|
||
|
|
openmetrics_data_model.proto
|
||
|
|
```
|