diff --git a/plugins/inputs/github/README.md b/plugins/inputs/github/README.md index 82534c1c8..a1bc7d8e3 100644 --- a/plugins/inputs/github/README.md +++ b/plugins/inputs/github/README.md @@ -1,9 +1,18 @@ # GitHub Input Plugin -Gather repository information from [GitHub][] hosted repositories. +This plugin gathers information from projects and repositories hosted on +[GitHub][github]. -**Note:** Telegraf also contains the [webhook][] input which can be used as an -alternative method for collecting repository information. +> [!NOTE] +> Telegraf also contains the [webhook input plugin][webhook] which can be used +> as an alternative method for collecting repository information. + +⭐ Telegraf v1.11.0 +🏷️ applications +💻 all + +[github]: https://www.github.com +[webhook]: /plugins/inputs/webhooks/github ## Global configuration options @@ -60,11 +69,11 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. - stars (int) - watchers (int) -When the [internal][] input is enabled: +When the [internal][internal] input is enabled: - internal_github - tags: - - access_token - An obfuscated reference to the configured access token or "Unauthenticated" + - access_token - obfuscated reference to access token or "Unauthenticated" - fields: - limit - How many requests you are limited to (per hour) - remaining - How many requests you have remaining (per hour) @@ -88,6 +97,4 @@ github_repository,language=Go,license=MIT\ License,name=telegraf,owner=influxdat internal_github,access_token=Unauthenticated closed_pull_requests=3522i,rate_limit_remaining=59i,rate_limit_limit=60i,rate_limit_blocks=0i,open_pull_requests=260i 1552653551000000000 ``` -[GitHub]: https://www.github.com [internal]: /plugins/inputs/internal -[webhook]: /plugins/inputs/webhooks/github diff --git a/plugins/inputs/gnmi/README.md b/plugins/inputs/gnmi/README.md index 5847e63c3..2c0fa4681 100644 --- a/plugins/inputs/gnmi/README.md +++ b/plugins/inputs/gnmi/README.md @@ -1,18 +1,18 @@ # gNMI (gRPC Network Management Interface) Input Plugin -This plugin consumes telemetry data based on the [gNMI][1] Subscribe method. TLS -is supported for authentication and encryption. This input plugin is -vendor-agnostic and is supported on any platform that supports the gNMI spec. +This plugin consumes telemetry data based on [gNMI][gnmi] subscriptions. TLS is +supported for authentication and encryption. This plugin is vendor-agnostic and +is supported on any platform that supports the gNMI specification. -For Cisco devices: +For Cisco devices the plugin has been optimized to support gNMI telemetry as +produced by Cisco IOS XR (64-bit) version 6.5.1, Cisco NX-OS 9.3 and +Cisco IOS XE 16.12 and later. -It has been optimized to support gNMI telemetry as produced by Cisco IOS XR -(64-bit) version 6.5.1, Cisco NX-OS 9.3 and Cisco IOS XE 16.12 and later. +⭐ Telegraf v1.15.0 +🏷️ network +💻 all -[1]: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md - -Please check the [troubleshooting section](#troubleshooting) in case of -problems, e.g. when getting an *empty metric-name warning*! +[gnmi]: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md ## Service Input diff --git a/plugins/inputs/google_cloud_storage/README.md b/plugins/inputs/google_cloud_storage/README.md index b2a0d3d47..73996566f 100644 --- a/plugins/inputs/google_cloud_storage/README.md +++ b/plugins/inputs/google_cloud_storage/README.md @@ -1,7 +1,14 @@ # Google Cloud Storage Input Plugin -The Google Cloud Storage plugin will collect metrics -on the given Google Cloud Storage Buckets. +This plugin will collect metrics from the given [Google Cloud Storage][gcs] +buckets in any of the supported [data formats][data_formats]. + +⭐ Telegraf v1.25.0 +🏷️ cloud, datastore +💻 all + +[gcs]: https://cloud.google.com/storage +[data_formats]: /docs/DATA_FORMATS_INPUT.md ## Global configuration options @@ -43,9 +50,8 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Metrics -- Measurements will reside on Google Cloud Storage with the format specified - -- example when [[inputs.google_cloud_storage.data_format]] is json +Measurements will reside on Google Cloud Storage with the format specified, for +example like ```json { @@ -66,6 +72,8 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. } ``` +when the [data format][data_formats] is set to `json`. + ## Example Output ```text diff --git a/plugins/inputs/graylog/README.md b/plugins/inputs/graylog/README.md index c83c9cc8e..987e06ff4 100644 --- a/plugins/inputs/graylog/README.md +++ b/plugins/inputs/graylog/README.md @@ -1,17 +1,23 @@ # GrayLog Input Plugin -The Graylog plugin can collect data from remote Graylog service URLs. +This plugin collects data from [Graylog servers][graylog], currently supporting +two type of end points `multiple` +(e.g. `http://:9000/api/system/metrics/multiple`) and `namespace` +(e.g. `http://:9000/api/system/metrics/namespace/{namespace}`). -Plugin currently support two type of end points:- +Multiple endpoint can be queried and mixing `multiple` and serveral `namespace` +end points is possible. Check `http://:9000/api/api-browser` for the full +list of available endpoints. -- multiple (e.g. `http://[graylog-server-ip]:9000/api/system/metrics/multiple`) -- namespace (e.g. `http://[graylog-server-ip]:9000/api/system/metrics/namespace/{namespace}`) +> [!NOTE] +> When specifying a `namespace` endpoint without an actual namespace, the +> metrics array will be ignored. -End Point can be a mix of one multiple end point and several namespaces end -points +⭐ Telegraf v1.0.0 +🏷️ logging +💻 all -Note: if namespace end point specified metrics array will be ignored for that -call. +[graylog]: https://graylog.org/ ## Global configuration options @@ -65,7 +71,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # insecure_skip_verify = false ``` -Please refer to GrayLog metrics api browser for full metric end points: +Please refer to GrayLog metrics API browser for full metric end points: `http://host:9000/api/api-browser` ## Metrics diff --git a/plugins/inputs/haproxy/README.md b/plugins/inputs/haproxy/README.md index 48b24eebf..22acf44cd 100644 --- a/plugins/inputs/haproxy/README.md +++ b/plugins/inputs/haproxy/README.md @@ -1,11 +1,13 @@ # HAProxy Input Plugin -The [HAProxy](http://www.haproxy.org/) input plugin gathers [statistics][1] -using the [stats socket][2] or [HTTP statistics page][3] of a HAProxy server. +This plugin gathers statistics of [HAProxy][haproxy] servers using sockets or +the HTTP protocol. -[1]: https://cbonte.github.io/haproxy-dconv/1.9/intro.html#3.3.16 -[2]: https://cbonte.github.io/haproxy-dconv/1.9/management.html#9.3 -[3]: https://cbonte.github.io/haproxy-dconv/1.9/management.html#9 +⭐ Telegraf v0.1.5 +🏷️ network, server +💻 all + +[haproxy]: http://www.haproxy.org/ ## Global configuration options diff --git a/plugins/inputs/hddtemp/README.md b/plugins/inputs/hddtemp/README.md index 00f407466..a528a8aa9 100644 --- a/plugins/inputs/hddtemp/README.md +++ b/plugins/inputs/hddtemp/README.md @@ -1,21 +1,26 @@ # HDDtemp Input Plugin -This plugin reads data from hddtemp daemon. +This plugin reads data from a [hddtemp][hddtemp] daemon. -Hddtemp should be installed and its daemon running. +> [!IMPORTANT] +> This plugin requires `hddtemp` to be installed and running as a daemon. -## OS Support & Alternatives +As the upstream project is not activly maintained anymore and various +distributions (e.g. Debian Bookwork and later) don't ship packages for `hddtemp` +anymore, the binary might not be available (e.g. in Ubuntu 22.04 or later). -This plugin depends on the availability of the `hddtemp` binary. The upstream -project is not active and Debian made the decision to remove it in Debian -Bookworm. This means the rest of the Debian ecosystem no longer has this binary -in later releases, like Ubuntu 22.04. +> [!TIP] +> As an alternative consider using the [smartctl][smartctl] relying on +> SMART information or [sensors][sensors] plugins to retrieve temperature data +> of your hard-drive. -As an alternative consider using the [`smartctl` plugin]. This parses the full -JSON output from `smartctl`, which includes temperature data, in addition to -much more data about devices in a system. +⭐ Telegraf v1.0.0 +🏷️ hardware, system +💻 all -[`smartctl` plugin]: ../smartctl/README.md +[hddtemp]: https://savannah.nongnu.org/projects/hddtemp/ +[smartctl]: /plugins/inputs/smartctl/README.md +[sensors]: /plugins/inputs/sensors/README.md ## Global configuration options diff --git a/plugins/inputs/http/README.md b/plugins/inputs/http/README.md index 7593762d8..db6bbd20c 100644 --- a/plugins/inputs/http/README.md +++ b/plugins/inputs/http/README.md @@ -1,10 +1,13 @@ # HTTP Input Plugin -The HTTP input plugin collects metrics from one or more HTTP(S) endpoints. The -endpoint should have metrics formatted in one of the supported [input data -formats](../../../docs/DATA_FORMATS_INPUT.md). Each data format has its own -unique set of configuration options which can be added to the input -configuration. +This plugin collects metrics from one or more HTTP endpoints providing data in +one of the supported [data formats][data_formats]. + +⭐ Telegraf v1.6.0 +🏷️ applications, server +💻 all + +[data_formats]: /docs/DATA_FORMATS_INPUT.md ## Global configuration options diff --git a/plugins/inputs/http_listener_v2/README.md b/plugins/inputs/http_listener_v2/README.md index a8abcf9d9..fc19a4357 100644 --- a/plugins/inputs/http_listener_v2/README.md +++ b/plugins/inputs/http_listener_v2/README.md @@ -1,18 +1,22 @@ # HTTP Listener v2 Input Plugin -The HTTP Listener v2 is a service input plugin that listens for metrics sent -via HTTP. Metrics may be sent in any supported [data-format][data_format]. +This plugin listens for metrics sent via HTTP in any of the supported +[data formats][data_formats]. > [!NOTE] > If you would like Telegraf to act as a proxy/relay for InfluxDB v1 or > InfluxDB v2 it is recommended to use the -> [`influxdb__listener`][influxdb_listener] or -> [`influxdb_v2_listener`][influxdb_v2_listener] plugin instead. +> [influxdb__listener][influxdb_listener] or +> [influxdb_v2_listener][influxdb_v2_listener] plugin instead. -⭐ Telegraf v1.30.0 -🏷️ servers, web +⭐ Telegraf v1.9.0 +🏷️ server 💻 all +[data_formats]: /docs/DATA_FORMATS_INPUT.md +[influxdb_listener]: /plugins/inputs/influxdb_listener/README.md +[influxdb_v2_listener]: /plugins/inputs/influxdb_v2_listener/README.md + ## Service Input This plugin is a service input. Normal plugins gather metrics determined by the @@ -137,7 +141,3 @@ Send query params: ```shell curl -i -XGET 'http://localhost:8080/telegraf?host=server01&value=0.42' ``` - -[data_format]: /docs/DATA_FORMATS_INPUT.md -[influxdb_listener]: /plugins/inputs/influxdb_listener/README.md -[influxdb_v2_listener]: /plugins/inputs/influxdb_v2_listener/README.md diff --git a/plugins/inputs/http_response/README.md b/plugins/inputs/http_response/README.md index ef549788c..6a5eb8843 100644 --- a/plugins/inputs/http_response/README.md +++ b/plugins/inputs/http_response/README.md @@ -1,6 +1,11 @@ # HTTP Response Input Plugin -This input plugin checks HTTP/HTTPS connections. +This plugin generates metrics from HTTP responses including the status code and +response statistics. + +⭐ Telegraf v0.12.1 +🏷️ server +💻 all ## Global configuration options diff --git a/plugins/inputs/hugepages/README.md b/plugins/inputs/hugepages/README.md index fd8a91b22..ecc84162e 100644 --- a/plugins/inputs/hugepages/README.md +++ b/plugins/inputs/hugepages/README.md @@ -1,12 +1,15 @@ # Hugepages Input Plugin -Transparent Huge Pages (THP) is a Linux memory management system that reduces +This plugin gathers metrics from the Linux' +[Transparent Huge Pages (THP) memory management system][hugetlb] that reduces the overhead of Translation Lookaside Buffer (TLB) lookups on machines with -large amounts of memory by using larger memory pages. +large amounts of memory. -Consult [the website][website] for more details. +⭐ Telegraf v1.22.0 +🏷️ system +💻 linux -[website]: https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html +[hugetlb]: https://www.kernel.org/doc/html/latest/admin-guide/mm/hugetlbpage.html ## Global configuration options diff --git a/plugins/inputs/icinga2/README.md b/plugins/inputs/icinga2/README.md index 1e4e9350c..d2e8aa053 100644 --- a/plugins/inputs/icinga2/README.md +++ b/plugins/inputs/icinga2/README.md @@ -1,12 +1,13 @@ # Icinga2 Input Plugin -This plugin gather services & hosts status using Icinga2 Remote API. +This plugin gather services and hosts status information using the +[Icinga2 remote API][remote_api]. -The icinga2 plugin uses the icinga2 remote API to gather status on running -services and hosts. You can read Icinga2's documentation for their remote API -[here][1]. +⭐ Telegraf v1.8.0 +🏷️ network, server, system +💻 all -[1]: https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api +[remote_api]: https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api ## Global configuration options diff --git a/plugins/inputs/infiniband/README.md b/plugins/inputs/infiniband/README.md index 7deb92521..f305f6a07 100644 --- a/plugins/inputs/infiniband/README.md +++ b/plugins/inputs/infiniband/README.md @@ -6,7 +6,9 @@ system. These are the counters that can be found in and RDMA counters can be found in `/sys/class/infiniband//ports//hw_counters/` -**Supported Platforms**: Linux +⭐ Telegraf v1.14.0 +🏷️ network +💻 linux ## Global configuration options diff --git a/plugins/inputs/influxdb/README.md b/plugins/inputs/influxdb/README.md index 3b4e150dd..0fecf6e37 100644 --- a/plugins/inputs/influxdb/README.md +++ b/plugins/inputs/influxdb/README.md @@ -1,28 +1,29 @@ # InfluxDB Input Plugin -The InfluxDB plugin will collect metrics on the given InfluxDB v1 servers from -the `/debug/vars` endpoint. Read the [documentation][1] for detailed -information about `influxdb` metrics. For InfluxDB v2 and the `metrics` -endpoint please see the section below. +This plugin collects metrics on the given InfluxDB v1 servers from the +`/debug/vars` endpoint. Read the [documentation][doc_v1] for detailed +information about `influxdb` metrics. -This plugin can also gather metrics from endpoints that expose -InfluxDB-formatted endpoints. See below for more information. +Additionally, this plugin can gather metrics from endpoints exposing +InfluxDB-formatted endpoints. -[1]: https://docs.influxdata.com/platform/monitoring/influxdata-platform/tools/measurements-internal/ +> [!TIP] +> To gather [InfluxDB v2 metrics][docs_v2] use the +> [prometheus plugin][prometheus] with +> +> ```toml +> [[inputs.prometheus]] +> urls = ["http://localhost:8086/metrics"] +> metric_version = 1 +> ``` -## InfluxDB v2 Metrics +⭐ Telegraf v0.2.5 +🏷️ datastores +💻 all -For [InfluxDB v2 metrics][2] are produced in Prometheus plain-text format. To -collect metrics at the new `/metrics` endpoint, please use the Prometheus -input plugin. This is an example to collect from a local database: - -```toml -[[inputs.prometheus]] - urls = ["http://localhost:8086/metrics"] - metric_version = 1 -``` - -[2]: https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/ +[doc_v1]: https://docs.influxdata.com/platform/monitoring/influxdata-platform/tools/measurements-internal/ +[docs_v2]: https://docs.influxdata.com/influxdb/latest/reference/internals/metrics/ +[prometheus]: /plugins/inputs/prometheus/README.md ## Global configuration options @@ -63,10 +64,26 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. timeout = "5s" ``` +## InfluxDB-formatted endpoints + +The influxdb plugin can collect InfluxDB-formatted data from JSON endpoints. +Whether associated with an Influx database or not. + +With a configuration of: + +```toml +[[inputs.influxdb]] + urls = [ + "http://127.0.0.1:8086/debug/vars", + "http://192.168.2.1:8086/debug/vars" + ] +``` + ## Metrics -**Note:** The measurements and fields included in this plugin are dynamically -built from the InfluxDB source, and may vary between versions: +> [!NOTE] +> The measurements and fields included in this plugin are dynamically +> built from the InfluxDB source, and may vary between versions. - **influxdb_ae** _(Enterprise Only)_ : Statistics related to the Anti-Entropy (AE) engine in InfluxDB Enterprise clusters. @@ -440,18 +457,3 @@ influxdb_tsm1_wal,database=_internal,host=tyrion,path=/Users/sparrc/.influxdb/wa influxdb_write,host=tyrion,url=http://localhost:8086/debug/vars pointReq=7274,pointReqLocal=7274,req=280,subWriteOk=280,writeOk=280 1463590500247354636 influxdb_shard,host=tyrion n_shards=4i 1463590500247354636 ``` - -## InfluxDB-formatted endpoints - -The influxdb plugin can collect InfluxDB-formatted data from JSON endpoints. -Whether associated with an Influx database or not. - -With a configuration of: - -```toml -[[inputs.influxdb]] - urls = [ - "http://127.0.0.1:8086/debug/vars", - "http://192.168.2.1:8086/debug/vars" - ] -``` diff --git a/plugins/inputs/influxdb_listener/README.md b/plugins/inputs/influxdb_listener/README.md index 4cc9d8477..fb1529048 100644 --- a/plugins/inputs/influxdb_listener/README.md +++ b/plugins/inputs/influxdb_listener/README.md @@ -1,22 +1,30 @@ # InfluxDB Listener Input Plugin -InfluxDB Listener is a service input plugin that listens for requests sent -according to the [InfluxDB HTTP API][influxdb_http_api]. The intent of the -plugin is to allow Telegraf to serve as a proxy/router for the `/write` -endpoint of the InfluxDB HTTP API. +This plugin listens for requests sent according to the +[InfluxDB HTTP v1 API][influxdb_http_api]. This allows Telegraf to serve as a +proxy/router for the `/write` endpoint of the InfluxDB HTTP API. -**Note:** This plugin was previously known as `http_listener`. If you wish to -send general metrics via HTTP it is recommended to use the -[`http_listener_v2`][http_listener_v2] instead. +> [!NOTE] +> This plugin was previously known as `http_listener`. If you wish to +> send general metrics via HTTP it is recommended to use the +> [`http_listener_v2`][http_listener_v2] instead. The `/write` endpoint supports the `precision` query parameter and can be set to one of `ns`, `u`, `ms`, `s`, `m`, `h`. All other parameters are ignored and defer to the output plugins configuration. -When chaining Telegraf instances using this plugin, CREATE DATABASE requests -receive a 200 OK response with message body `{"results":[]}` but they are not -relayed. The output configuration of the Telegraf instance which ultimately -submits data to InfluxDB determines the destination database. +> [!IMPORTANT] +> When chaining Telegraf instances using this plugin, `CREATE DATABASE` requests +> receive a `200 OK` response with message body `{"results":[]}` but they are +> not relayed. The configuration of the output plugin ultimately submits data +> to InfluxDB determines the destination database. + +⭐ Telegraf v1.9.0 +🏷️ datastores +💻 all + +[influxdb_http_api]: https://docs.influxdata.com/influxdb/v1.8/guides/write_data/ +[http_listener_v2]: /plugins/inputs/http_listener_v2/README.md ## Service Input @@ -102,15 +110,16 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. Metrics are created from InfluxDB Line Protocol in the request body. -## Troubleshooting +## Example Output -**Example Query:** +Using ```sh curl -i -XPOST 'http://localhost:8186/write' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000' ``` -[influxdb_http_api]: https://docs.influxdata.com/influxdb/v1.8/guides/write_data/ -[http_listener_v2]: /plugins/inputs/http_listener_v2/README.md +will produce the following metric -## Example Output +```text +cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000 +``` diff --git a/plugins/inputs/influxdb_v2_listener/README.md b/plugins/inputs/influxdb_v2_listener/README.md index 8cd16b756..118496a0a 100644 --- a/plugins/inputs/influxdb_v2_listener/README.md +++ b/plugins/inputs/influxdb_v2_listener/README.md @@ -1,15 +1,18 @@ # InfluxDB V2 Listener Input Plugin -InfluxDB V2 Listener is a service input plugin that listens for requests sent -according to the [InfluxDB HTTP API][influxdb_http_api]. The intent of the -plugin is to allow Telegraf to serve as a proxy/router for the `/api/v2/write` -endpoint of the InfluxDB HTTP API. +This plugin listens for requests sent according to the +[InfluxDB HTTP v2 API][influxdb_http_api]. This allows Telegraf to serve as a +proxy/router for the `/api/v2/write` endpoint of the InfluxDB HTTP API. The `/api/v2/write` endpoint supports the `precision` query parameter and can be set to one of `ns`, `us`, `ms`, `s`. All other parameters are ignored and defer to the output plugins configuration. -Telegraf minimum version: Telegraf 1.16.0 +⭐ Telegraf v1.16.0 +🏷️ datastores +💻 all + +[influxdb_http_api]: https://docs.influxdata.com/influxdb/v2/api/ ## Service Input @@ -90,14 +93,16 @@ to use them. Metrics are created from InfluxDB Line Protocol in the request body. -## Troubleshooting +## Example Output -**Example Query:** +Using ```sh curl -i -XPOST 'http://localhost:8186/api/v2/write' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000' ``` -[influxdb_http_api]: https://docs.influxdata.com/influxdb/latest/api/ +will produce the following metric -## Example Output +```text +cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000 +``` diff --git a/plugins/inputs/intel_baseband/README.md b/plugins/inputs/intel_baseband/README.md index 184cece71..542486922 100644 --- a/plugins/inputs/intel_baseband/README.md +++ b/plugins/inputs/intel_baseband/README.md @@ -1,33 +1,36 @@ # Intel Baseband Accelerator Input Plugin -Intel Baseband Accelerator Input Plugin collects metrics from both dedicated and -integrated Intel devices that provide Wireless Baseband hardware acceleration. -These devices play a key role in accelerating 5G and 4G Virtualized Radio Access -Networks (vRAN) workloads, increasing the overall compute capacity of -a commercial, off-the-shelf platforms. - -Intel Baseband devices integrate various features critical for 5G and -LTE (Long Term Evolution) networks, including e.g.: +This plugin collects metrics from both dedicated and integrated Intel devices +providing Wireless Baseband hardware acceleration. These devices play a key role +in accelerating 5G and 4G Virtualized Radio Access Networks (vRAN) workloads, +increasing the overall compute capacity of commercial, off-the-shelf platforms +by integrating e.g. - Forward Error Correction (FEC) processing, - 4G Turbo FEC processing, - 5G Low Density Parity Check (LDPC) -- a Fast Fourier Transform (FFT) block providing DFT/iDFT processing offload -for the 5G Sounding Reference Signal (SRS) +- Fast Fourier Transform (FFT) block providing DFT/iDFT processing offload for + the 5G Sounding Reference Signal (SRS) -Supported hardware: +⭐ Telegraf v1.27.0 +🏷️ hardware, network, system +💻 linux + +## Requirements + +- supported Intel Baseband device installed and configured +- Linux kernel 5.7+ +- [pf-bb-config](https://github.com/intel/pf-bb-config) (version >= v23.03) + installed and running + +This plugin supports the following hardware: - Intel® vRAN Boost integrated accelerators: - - 4th Gen Intel® Xeon® Scalable processor with Intel® vRAN Boost (also known as Sapphire Rapids Edge Enhanced / SPR-EE) + - 4th Gen Intel® Xeon® Scalable processor with Intel® vRAN Boost + (also known as Sapphire Rapids Edge Enhanced / SPR-EE) - External expansion cards connected to the PCI bus: - Intel® vRAN Dedicated Accelerator ACC100 SoC (code named Mount Bryce) -## Prerequisites - -- Intel Baseband device installed and configured. -- Minimum Linux kernel version required is 5.7. -- [pf-bb-config](https://github.com/intel/pf-bb-config) (version >= v23.03) installed and running. - For more information regarding system configuration, please follow DPDK installation guides: diff --git a/plugins/inputs/intel_dlb/README.md b/plugins/inputs/intel_dlb/README.md index ab0c53720..7c8d5c693 100644 --- a/plugins/inputs/intel_dlb/README.md +++ b/plugins/inputs/intel_dlb/README.md @@ -1,53 +1,25 @@ -# Intel® Dynamic Load Balancer (Intel® DLB) Input Plugin +# Intel® Dynamic Load Balancer Input Plugin -The `Intel DLB` plugin collects metrics exposed by applications built with -[Data Plane Development Kit](https://www.dpdk.org/) which is an extensive -set of open source libraries designed for accelerating packet processing -workloads, plugin is also using bifurcated driver. More specifically it's -targeted for applications that use Intel DLB as eventdev devices accessed -via bifurcated driver (allowing access from kernel and user-space). +This plugin collects metrics exposed by applications built with the +[Data Plane Development Kit][dpdk], an extensive set of open source libraries +designed for accelerating packet processing workloads, plugin is also using +bifurcated driver. More specifically it's targeted for applications using +Intel DLB as eventdev devices accessed via bifurcated driver +(allowing access from kernel and user-space). -## Metrics +⭐ Telegraf v1.25.0 +🏷️ applications +💻 linux -There are two sources of metrics: +[dpdk]: https://www.dpdk.org/ -- DPDK-based app for detailed eventdev metrics per device, per port and per queue -- Sysfs entries from kernel driver for RAS metrics - -## About Intel® Dynamic Load Balancer (Intel® DLB) - -The Intel® Dynamic Load Balancer (Intel® DLB) is a PCIe device that provides -load-balanced, prioritized scheduling of events (that is, packets) across -CPU cores enabling efficient core-to-core communication. It is a hardware -accelerator located inside the latest Intel® Xeon® devices offered by Intel. -It supports the event-driven programming model of DPDK's Event Device Library. -This library is used in packet processing pipelines for multi-core scalability, -dynamic load-balancing, and variety of packet distribution and synchronization -schemes. - -## About DPDK Event Device Library - -The DPDK Event device library is an abstraction that provides the application -with features to schedule events. The eventdev framework introduces the event -driven programming model. In a polling model, lcores poll ethdev ports and -associated Rx queues directly to look for a packet. By contrast in an event -driven model, lcores call the scheduler that selects packets for them based on -programmer-specified criteria. The Eventdev library adds support for an event -driven programming model, which offers applications automatic multicore scaling, -dynamic load balancing, pipelining, packet ingress order maintenance and -synchronization services to simplify application packet processing. -By introducing an event driven programming model, DPDK can support -both polling and event driven programming models for packet processing, -and applications are free to choose whatever model (or combination of the two) -best suits their needs. - -## Prerequisites +## Requirements +- Linux kernel 5.12+ - [DLB >= v7.4](https://www.intel.com/content/www/us/en/download/686372/intel-dynamic-load-balancer.html) - [DPDK >= 20.11.3](http://core.dpdk.org/download/) -- Linux kernel >= 5.12 -> **NOTE:** It may happen that sysfs entries or the socket telemetry interface +> [!NOTE] It may happen that sysfs entries or the socket telemetry interface > exposed by DPDK-based app will require root access. This means that either > access permissions have to be adjusted for sysfs / socket telemetry > interface to allow Telegraf to access it, or Telegraf should run with root @@ -97,6 +69,13 @@ reported via `/eventdev/` command: - `/eventdev/queue_xstats` - `/eventdev/queue_links` +## Metrics + +There are two sources of metrics: + +- DPDK-based app for detailed eventdev metrics per device, per port and per queue +- Sysfs entries from kernel driver for RAS metrics + ## Example Output ```text diff --git a/plugins/inputs/intel_pmt/README.md b/plugins/inputs/intel_pmt/README.md index f888ea8c3..adf851296 100644 --- a/plugins/inputs/intel_pmt/README.md +++ b/plugins/inputs/intel_pmt/README.md @@ -1,24 +1,49 @@ -# Intel® Platform Monitoring Technology (Intel® PMT) Input Plugin +# Intel® Platform Monitoring Technology Input Plugin This plugin collects metrics via the Linux kernel driver for -Intel® Platform Monitoring Technology (Intel® PMT). -Intel® PMT is an architecture capable of enumerating -and accessing hardware monitoring capabilities on a supported device. +Intel® Platform Monitoring Technology (Intel® PMT), an architecture capable of +enumerating and accessing hardware monitoring capabilities on supported devices. -Support has been added to the mainline Linux kernel under the -platform driver (`drivers/platform/x86/intel/pmt`) which exposes -the Intel PMT telemetry space as a sysfs entry at -`/sys/class/intel_pmt/`. Each discovered telemetry aggregator is -exposed as a directory (with a `telem` prefix) containing a `guid` -identifying the unique PMT space. This file is associated with a -set of XML specification files which can be found in the -[Intel-PMT Repository]. +⭐ Telegraf v1.28.0 +🏷️ hardware, system +💻 linux -This plugin discovers and parses the telemetry data exposed by -the kernel driver using the specification inside the XML files. -Furthermore, the plugin then reads low level samples/counters -and evaluates high level samples/counters according to -transformation formulas, and then reports the collected values. +## Requirements + +- supported device +- Linux kernel >= 5.11 +- `intel_pmt_telemetry` module loaded (on kernels 5.11-5.14) +- `intel_pmt` module loaded (on kernels 5.14+) + +This plugin supports devices exposing PMT, e.g. + +- 4th Generation Intel® Xeon® Scalable Processors (Sapphire Rapids / SPR) +- 6th Generation Intel® Xeon® Scalable Processors (Granite Rapids / GNR) + +Support has been added to the mainline Linux kernel under the platform driver +(`drivers/platform/x86/intel/pmt`) which exposes the Intel PMT telemetry space +as a sysfs entry at `/sys/class/intel_pmt/`. Each discovered telemetry +aggregator is exposed as a directory (with a `telem` prefix) containing a `guid` +identifying the unique PMT space. This file is associated with a set of XML +specification files which can be found in the [Intel-PMT Repository][repo]. +The XML specification must be specified as an absolute path to the `pmt.xml` +file using the `spec` setting . + +This plugin discovers and parses the telemetry data exposed by the kernel driver +using the specification inside the XML files. Furthermore, the plugin then reads +low level samples/counters and evaluates high level samples/counters according +to transformation formulas, and then reports the collected values. + +> [!IMPORTANT] +> PMT space is located in `/sys/class/intel_pmt` with `telem` files requiring +> **root privileges** to be read. If Telegraf is not running as root you should +> add the following capability to the Telegraf executable: +> +> ```sh +> sudo setcap cap_dac_read_search+ep /usr/bin/telegraf +> ``` + +[repo]: https://github.com/intel/Intel-PMT ## Global configuration options @@ -29,14 +54,6 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. [CONFIGURATION.md]: ../../../docs/CONFIGURATION.md#plugins -## Requirements - -Intel PMT Input Plugin requires an XML specification as `spec`. -It can be provided as a filepath. - -The provided filepath should be an absolute path to `pmt.xml` within -local copies of XML files from the cloned [Intel-PMT Repository]. - ## Configuration ```toml @sample.conf @@ -60,78 +77,7 @@ local copies of XML files from the cloned [Intel-PMT Repository]. # samples_enabled = [] ``` -## Example Configuration: C-State residency and temperature with a datatype metric filter - -This configuration allows getting only a subset of metrics -with the use of a datatype filter: - -```toml -[[inputs.intel_pmt]] - spec = "/home/telegraf/Intel-PMT/xml/pmt.xml" - datatypes_enabled = ["tbandwidth_28b","ttemperature"] -``` - -## Example Configuration: C-State residency and temperature with a sample metric filter - -This configuration allows getting only a subset of metrics -with the use of a sample filter: - -```toml -[[inputs.intel_pmt]] - spec = "/home/telegraf/Intel-PMT/xml/pmt.xml" - samples_enabled = ["C0Residency","C1Residency", "Cx_TEMP"] -``` - -## Prerequisites - -Minimum Linux kernel version 5.11 with - -- the `intel_pmt_telemetry` module loaded (on kernels 5.11-5.14) -- the `intel_pmt` module loaded (on kernels 5.14+) - -Intel PMT is exposed on a limited number of devices, e.g. - -- 4th Generation Intel® Xeon® Scalable Processors -(codenamed Sapphire Rapids / SPR) -- 6th Generation Intel® Xeon® Scalable Processors -(codenamed Granite Rapids / GNR) - -PMT space is located in `/sys/class/intel_pmt` with `telem` files requiring -root privileges to read. - -### If Telegraf is not running as a root user - -By default, the `telem` binary file requires root privileges to be read. - -To avoid running Telegraf as a root, -add the following capability to the Telegraf executable: - -```sh -sudo setcap cap_dac_read_search+ep /usr/bin/telegraf -``` - -## Metrics - -All metrics have the following tags: - -- `guid` (unique id of an Intel PMT space). -- `numa_node` (NUMA node the sample is collected from). -- `pci_bdf` (PCI Bus:Device.Function (BDF) the sample is collected from). -- `sample_name` (name of the gathered sample). -- `sample_group` (name of a group to which the sample belongs). -- `datatype_idref` (datatype to which the sample belongs). - -`sample_name` prefixed in XMLs with `Cx_` where `x` -is the core number also have the following tag: - -- `core` (core to which the metric relates). - -`sample_name` prefixed in XMLs with `CHAx_` where `x` -is the CHA number also have the following tag: - -- `cha` (Caching and Home Agent to which the metric relates). - -## Enabling metrics +### Enabling metrics By default, the plugin collects all available metrics. @@ -277,6 +223,49 @@ See the table below for available datatypes and related metrics: | `ttw_unit` | `TW` | Time window. Valid TW range is 0 to 17. The unit is calculated as `2.3 * 2^TW` ms (e.g. `2.3 * 2^17` ms = ~302 seconds). | | `tcore_stress_level` | `STRESS_LEVEL` | Accumulating counter indicating relative stress level for a core (per core) | +### Example: C-State residency and temperature with a datatype metric filter + +This configuration allows getting only a subset of metrics +with the use of a datatype filter: + +```toml +[[inputs.intel_pmt]] + spec = "/home/telegraf/Intel-PMT/xml/pmt.xml" + datatypes_enabled = ["tbandwidth_28b","ttemperature"] +``` + +### Example: C-State residency and temperature with a sample metric filter + +This configuration allows getting only a subset of metrics +with the use of a sample filter: + +```toml +[[inputs.intel_pmt]] + spec = "/home/telegraf/Intel-PMT/xml/pmt.xml" + samples_enabled = ["C0Residency","C1Residency", "Cx_TEMP"] +``` + +## Metrics + +All metrics have the following tags: + +- `guid` (unique id of an Intel PMT space). +- `numa_node` (NUMA node the sample is collected from). +- `pci_bdf` (PCI Bus:Device.Function (BDF) the sample is collected from). +- `sample_name` (name of the gathered sample). +- `sample_group` (name of a group to which the sample belongs). +- `datatype_idref` (datatype to which the sample belongs). + +`sample_name` prefixed in XMLs with `Cx_` where `x` +is the core number also have the following tag: + +- `core` (core to which the metric relates). + +`sample_name` prefixed in XMLs with `CHAx_` where `x` +is the CHA number also have the following tag: + +- `cha` (Caching and Home Agent to which the metric relates). + ## Example Output Example output with `tpvp_throttle_counter` as a datatype metric filter: @@ -411,5 +400,3 @@ intel_pmt,core=61,datatype_idref=tpvp_throttle_counter,guid=0x87b6fef1,pmt,numa_ intel_pmt,core=62,datatype_idref=tpvp_throttle_counter,guid=0x87b6fef1,pmt,numa_node=0,pci_bdf=0000:e7:03.1,sample_group=C62_PVP_THROTTLE_1024,sample_name=PVP_THROTTLE_1024 value=0i 1693766334000000000 intel_pmt,core=63,datatype_idref=tpvp_throttle_counter,guid=0x87b6fef1,pmt,numa_node=0,pci_bdf=0000:e7:03.1,sample_group=C63_PVP_THROTTLE_1024,sample_name=PVP_THROTTLE_1024 value=0i 1693766334000000000 ``` - -[Intel-PMT repository]: https://github.com/intel/Intel-PMT diff --git a/plugins/inputs/intel_pmu/README.md b/plugins/inputs/intel_pmu/README.md index e8a23a08c..9a51754e0 100644 --- a/plugins/inputs/intel_pmu/README.md +++ b/plugins/inputs/intel_pmu/README.md @@ -1,19 +1,41 @@ # Intel Performance Monitoring Unit Plugin -This input plugin exposes Intel PMU (Performance Monitoring Unit) metrics -available through [Linux Perf](https://perf.wiki.kernel.org/index.php/Main_Page) -subsystem. +This plugin gathers Intel Performance Monitoring Unit metrics available via the +[Linux Perf][linux_perf] subsystem. -PMU metrics gives insight into performance and health of IA processor's internal -components, including core and uncore units. With the number of cores increasing -and processor topology getting more complex the insight into those metrics is -vital to assure the best CPU performance and utilization. +PMU metrics provide insights into performance and health of IA processors' +internal components, including core and uncore units. With the number of cores +increasing and processor topology getting more complex the insight into those +metrics is vital to assure the best CPU performance and utilization. Performance counters are CPU hardware registers that count hardware events such as instructions executed, cache-misses suffered, or branches mispredicted. They form a basis for profiling applications to trace dynamic control flow and identify hotspots. +⭐ Telegraf v1.21.0 +🏷️ hardware, system +💻 linux + +[linux_perf]: https://perf.wiki.kernel.org/index.php/Main_Page + +## Requirements + +The plugin uses the [iaevents library][iaevents_lib] that eases accessing the +Linux kernel's perf interface. + +> [!IMPORTANT] +> The Intel PMU plugin is only intended for use on **Linux 64-bit** systems. + +Event definition JSON files for specific architectures can be found at the +[Github repository][repo]. Download the event definitions appropriate for your +system e.g. using the [`event_download.py` PMU tool][pmu_tools] and keep them +in a safe place on your system. + +[iaevents_lib]: https://github.com/intel/iaevents +[repo]: https://github.com/intel/perfmon +[pmu_tools]: https://github.com/andikleen/pmu-tools + ## Global configuration options In addition to the plugin-specific configuration settings, plugins support @@ -104,20 +126,6 @@ where: | G | perf_event_attr.exclude_hv | don't count hypervisor | | D | perf_event_attr.pinned | must always be on PMU | -## Requirements - -The plugin is using [iaevents](https://github.com/intel/iaevents) library which -is a golang package that makes accessing the Linux kernel's perf interface -easier. - -Intel PMU plugin, is only intended for use on **linux 64-bit** systems. - -Event definition JSON files for specific architectures can be found at -[github](https://github.com/intel/perfmon). A script to download the event -definitions that are appropriate for your system (event_download.py) is -available at [pmu-tools](https://github.com/andikleen/pmu-tools). Please keep -these files in a safe place on your system. - ## Measuring Plugin allows measuring both core and uncore events. During plugin diff --git a/plugins/inputs/intel_powerstat/README.md b/plugins/inputs/intel_powerstat/README.md index b851df4cd..b08350186 100644 --- a/plugins/inputs/intel_powerstat/README.md +++ b/plugins/inputs/intel_powerstat/README.md @@ -1,16 +1,207 @@ # Intel PowerStat Input Plugin -This input plugin monitors power statistics on Intel-based platforms and -assumes presence of Linux based OS. +This plugin gathers power statistics on Intel-based platforms providing insights +into power saving and workload migration. Those are beneficial for Monitoring +and Analytics systems to take preventive or corrective actions based on platform +busyness, CPU temperature, actual CPU utilization and power statistics. -Not all CPUs are supported, please see the software and hardware dependencies -sections below to ensure platform support. +⭐ Telegraf v1.17.0 +🏷️ hardware, system +💻 linux -Main use cases are power saving and workload migration. Telemetry frameworks -allow users to monitor critical platform level metrics. Key source of platform -telemetry is power domain that is beneficial for MANO Monitoring&Analytics -systems to take preventive/corrective actions based on platform busyness, CPU -temperature, actual CPU utilization and power statistics. +## Requirements + +### Kernel modules + +Plugin is mostly based on Linux Kernel modules that expose specific metrics over +`sysfs` or `devfs` interfaces. The following dependencies are expected: + +- `intel-rapl` kernel module which exposes Intel Runtime Power Limiting metrics over + `sysfs` (`/sys/devices/virtual/powercap/intel-rapl`), +- `msr` kernel module that provides access to processor model specific + registers over `devfs` (`/dev/cpu/cpu%d/msr`), +- `cpufreq` kernel module - which exposes per-CPU Frequency over `sysfs` + (`/sys/devices/system/cpu/cpu%d/cpufreq/scaling_cur_freq`), +- `intel-uncore-frequency` kernel module exposes Intel uncore frequency metrics + over `sysfs` (`/sys/devices/system/cpu/intel_uncore_frequency`). + +Make sure the required kernel modules are loaded and running. Modules might have +to be manually enabled by using `modprobe`. Depending on the kernel version, +run the following commands: + +```sh +# rapl modules: +## kernel < 4.0 +sudo modprobe intel_rapl +## kernel >= 4.0 +sudo modprobe rapl +sudo modprobe intel_rapl_common +sudo modprobe intel_rapl_msr + +# msr module: +sudo modprobe msr + +# cpufreq module: +### integrated in kernel + +# intel-uncore-frequency module: +## only for kernel >= 5.6.0 +sudo modprobe intel-uncore-frequency +``` + +### Kernel's perf interface + +For perf-related metrics, when Telegraf is not running as root, the following +capability should be added to the Telegraf executable: + +```sh +sudo setcap cap_sys_admin+ep +``` + +Alternatively, `/proc/sys/kernel/perf_event_paranoid` has to be set to value +less than 1. + +Depending on environment and configuration (number of monitored CPUs and number +of enabled metrics), it might be required to increase the limit on the number of +open file descriptors allowed. This can be done for example by using `ulimit -n` +command. + +### Root privileges + +> [!IMPORTANT] +> Telegraf with Intel PowerStat plugin enabled may require root privileges to +> read all the metrics (depending on OS type or configuration). + +Alternatively, the following capabilities can be added to the Telegraf +executable: + +```sh +#without perf-related metrics: +sudo setcap cap_sys_rawio,cap_dac_read_search+ep + +#with perf-related metrics: +sudo setcap cap_sys_rawio,cap_dac_read_search,cap_sys_admin+ep +``` + +### Supported hardware + +Specific metrics require certain processor features to be present, otherwise +Intel PowerStat plugin won't be able to read them. The user can detect supported +processor features by reading `/proc/cpuinfo` file. +Plugin assumes crucial properties are the same for all CPU cores in the system. + +The following `processor` properties are examined in more detail +in this section: + +- `vendor_id` +- `cpu family` +- `model` +- `flags` + +The following processor properties are required by the plugin: + +- Processor `vendor_id` must be `GenuineIntel` and `cpu family` must be `6` - + since data used by the plugin are Intel-specific. +- The following processor flags shall be present: + - `msr` shall be present for plugin to read platform data from processor + model specific registers and collect the following metrics: + - `cpu_c0_state_residency` + - `cpu_c1_state_residency` + - `cpu_c3_state_residency` + - `cpu_c6_state_residency` + - `cpu_c7_state_residency` + - `cpu_busy_cycles` (**DEPRECATED** - superseded by `cpu_c0_state_residency_percent`) + - `cpu_busy_frequency` + - `cpu_temperature` + - `cpu_base_frequency` + - `max_turbo_frequency` + - `uncore_frequency` (for kernel < 5.18) + - `aperfmperf` shall be present to collect the following metrics: + - `cpu_c0_state_residency` + - `cpu_c1_state_residency` + - `cpu_busy_cycles` (**DEPRECATED** - superseded by `cpu_c0_state_residency_percent`) + - `cpu_busy_frequency` + - `dts` shall be present to collect: + - `cpu_temperature` +- supported CPU model. To see which metrics are supported by your `model`. The + following metrics exist: + - `cpu_c1_state_residency` + - `cpu_c3_state_residency` + - `cpu_c6_state_residency` + - `cpu_c7_state_residency` + - `cpu_temperature` + - `cpu_base_frequency` + - `uncore_frequency` + +### Supported CPU models + +| Model number | Processor name | `cpu_c1_state_residency`
`cpu_c6_state_residency`
`cpu_temperature`
`cpu_base_frequency` | `cpu_c3_state_residency` | `cpu_c7_state_residency` | `uncore_frequency` | +|--------------|---------------------------------|:----------------------------------------------------------------------------------------------------:|:------------------------:|:------------------------:|:------------------:| +| 0x1E | Intel Nehalem | ✓ | ✓ | | | +| 0x1F | Intel Nehalem-G | ✓ | ✓ | | | +| 0x1A | Intel Nehalem-EP | ✓ | ✓ | | | +| 0x2E | Intel Nehalem-EX | ✓ | ✓ | | | +| 0x25 | Intel Westmere | ✓ | ✓ | | | +| 0x2C | Intel Westmere-EP | ✓ | ✓ | | | +| 0x2F | Intel Westmere-EX | ✓ | ✓ | | | +| 0x2A | Intel Sandybridge | ✓ | ✓ | ✓ | | +| 0x2D | Intel Sandybridge-X | ✓ | ✓ | ✓ | | +| 0x3A | Intel Ivybridge | ✓ | ✓ | ✓ | | +| 0x3E | Intel Ivybridge-X | ✓ | ✓ | ✓ | | +| 0x3C | Intel Haswell | ✓ | ✓ | ✓ | | +| 0x3F | Intel Haswell-X | ✓ | ✓ | ✓ | | +| 0x45 | Intel Haswell-L | ✓ | ✓ | ✓ | | +| 0x46 | Intel Haswell-G | ✓ | ✓ | ✓ | | +| 0x3D | Intel Broadwell | ✓ | ✓ | ✓ | | +| 0x47 | Intel Broadwell-G | ✓ | ✓ | ✓ | ✓ | +| 0x4F | Intel Broadwell-X | ✓ | ✓ | | ✓ | +| 0x56 | Intel Broadwell-D | ✓ | ✓ | | ✓ | +| 0x4E | Intel Skylake-L | ✓ | ✓ | ✓ | | +| 0x5E | Intel Skylake | ✓ | ✓ | ✓ | | +| 0x55 | Intel Skylake-X | ✓ | | | ✓ | +| 0x8E | Intel KabyLake-L | ✓ | ✓ | ✓ | | +| 0x9E | Intel KabyLake | ✓ | ✓ | ✓ | | +| 0xA5 | Intel CometLake | ✓ | ✓ | ✓ | | +| 0xA6 | Intel CometLake-L | ✓ | ✓ | ✓ | | +| 0x66 | Intel CannonLake-L | ✓ | | ✓ | | +| 0x6A | Intel IceLake-X | ✓ | | | ✓ | +| 0x6C | Intel IceLake-D | ✓ | | | ✓ | +| 0x7D | Intel IceLake | ✓ | | | | +| 0x7E | Intel IceLake-L | ✓ | | ✓ | | +| 0x9D | Intel IceLake-NNPI | ✓ | | ✓ | | +| 0xA7 | Intel RocketLake | ✓ | | ✓ | | +| 0x8C | Intel TigerLake-L | ✓ | | ✓ | | +| 0x8D | Intel TigerLake | ✓ | | ✓ | | +| 0x8F | Intel Sapphire Rapids X | ✓ | | | ✓ | +| 0xCF | Intel Emerald Rapids X | ✓ | | | ✓ | +| 0xAD | Intel Granite Rapids X | ✓ | | | | +| 0xAE | Intel Granite Rapids D | ✓ | | | | +| 0x8A | Intel Lakefield | ✓ | | ✓ | | +| 0x97 | Intel AlderLake | ✓ | | ✓ | ✓ | +| 0x9A | Intel AlderLake-L | ✓ | | ✓ | ✓ | +| 0xB7 | Intel RaptorLake | ✓ | | ✓ | ✓ | +| 0xBA | Intel RaptorLake-P | ✓ | | ✓ | ✓ | +| 0xBF | Intel RaptorLake-S | ✓ | | ✓ | ✓ | +| 0xAC | Intel MeteorLake | ✓ | | ✓ | ✓ | +| 0xAA | Intel MeteorLake-L | ✓ | | ✓ | ✓ | +| 0xC6 | Intel ArrowLake | ✓ | | ✓ | | +| 0xBD | Intel LunarLake | ✓ | | ✓ | | +| 0x37 | Intel Atom® Bay Trail | ✓ | | | | +| 0x4D | Intel Atom® Avaton | ✓ | | | | +| 0x4A | Intel Atom® Merrifield | ✓ | | | | +| 0x5A | Intel Atom® Moorefield | ✓ | | | | +| 0x4C | Intel Atom® Airmont | ✓ | ✓ | | | +| 0x5C | Intel Atom® Apollo Lake | ✓ | ✓ | ✓ | | +| 0x5F | Intel Atom® Denverton | ✓ | | | | +| 0x7A | Intel Atom® Goldmont | ✓ | ✓ | ✓ | | +| 0x86 | Intel Atom® Jacobsville | ✓ | | | | +| 0x96 | Intel Atom® Elkhart Lake | ✓ | | ✓ | | +| 0x9C | Intel Atom® Jasper Lake | ✓ | | ✓ | | +| 0xBE | Intel AlderLake-N | ✓ | | ✓ | | +| 0xAF | Intel Sierra Forest | ✓ | | | | +| 0xB6 | Intel Grand Ridge | ✓ | | | | +| 0x57 | Intel Xeon® PHI Knights Landing | ✓ | | | | +| 0x85 | Intel Xeon® PHI Knights Mill | ✓ | | | | ## Global configuration options @@ -53,15 +244,13 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## "cpu_c0_substate_c02", "cpu_c0_substate_c0_wait" # cpu_metrics = [] - ## Optionally the user can choose for which CPUs metrics configured in cpu_metrics array should be gathered. - ## Can't be combined with excluded_cpus. - ## Empty or missing array means CPU metrics are gathered for all CPUs. + ## CPUs metrics to include from those configured in cpu_metrics array + ## Can't be combined with excluded_cpus. Empty means all CPUs are gathered. ## e.g. ["0-3", "4,5,6"] or ["1-3,4"] # included_cpus = [] - ## Optionally the user can choose which CPUs should be excluded from gathering metrics configured in cpu_metrics array. - ## Can't be combined with included_cpus. - ## Empty or missing array means CPU metrics are gathered for all CPUs. + ## CPUs metrics to exclude from those configured in cpu_metrics array + ## Can't be combined with included_cpus. Empty means all CPUs are gathered. ## e.g. ["0-3", "4,5,6"] or ["1-3,4"] # excluded_cpus = [] @@ -76,19 +265,51 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # msr_read_timeout = "0ms" ``` -### Configuration notes +1. The configuration of `included_cpus` or `excluded_cpus` may affect the + ability to collect `package_metrics`. Some of them + (`max_turbo_frequency`, `cpu_base_frequency`, and `uncore_frequency`) need to + read data from exactly one processor for each package. If `included_cpus` or + `excluded_cpus` exclude all processors from the package, reading th + mentioned metrics for that package will not be possible. +2. `event_definitions` JSON file for specific architecture can be found at + [perfmon][perfmon]. A script to download the event definition that is + appropriate for current environment (`event_download.py`) is available at + [pmu-tools][pmu_tools]. For perf-related metrics supported by this plugin, + an event definition JSON file with events for the `core` is required, e.g. + `sapphirerapids_core.json` or `GenuineIntel-6-8F-core.json`. -1. The configuration of `included_cpus` or `excluded_cpus` may affect the ability to collect `package_metrics`. - Some of them (`max_turbo_frequency`, `cpu_base_frequency`, and `uncore_frequency`) need to read data - from exactly one processor for each package. If `included_cpus` or `excluded_cpus` exclude all processors - from the package, reading the mentioned metrics for that package will not be possible. -2. `event_definitions` JSON file for specific architecture can be found at [perfmon](https://github.com/intel/perfmon). - A script to download the event definition that is appropriate for current environment (`event_download.py`) is - available at [pmu-tools](https://github.com/andikleen/pmu-tools). - For perf-related metrics supported by this plugin, an event definition JSON file - with events for the `core` is required. +[perfmon]: https://github.com/intel/perfmon +[pmu_tools]: https://github.com/andikleen/pmu-tools - For example: `sapphirerapids_core.json` or `GenuineIntel-6-8F-core.json`. +### Dependencies of metrics on system configuration + +Details of these dependencies are discussed above: + +| Configuration option | Type | Dependency | +|--------------------------------------------------------------------------|-------------------|-------------------| +| `current_power_consumption` | `package_metrics` | `rapl` module | +| `current_dram_power_consumption` | `package_metrics` | `rapl` module | +| `thermal_design_power` | `package_metrics` | `rapl` module | +| `max_turbo_frequency` | `package_metrics` | `msr` module | +| `uncore_frequency` | `package_metrics` | `intel-uncore-frequency` module* | +| `cpu_base_frequency` | `package_metrics` | `msr` module | +| `cpu_frequency` | `cpu_metrics` | `cpufreq` module | +| `cpu_c0_state_residency` | `cpu_metrics` | `msr` module | +| `cpu_c1_state_residency` | `cpu_metrics` | `msr` module | +| `cpu_c3_state_residency` | `cpu_metrics` | `msr` module | +| `cpu_c6_state_residency` | `cpu_metrics` | `msr` module | +| `cpu_c7_state_residency` | `cpu_metrics` | `msr` module | +| `cpu_busy_cycles` (**DEPRECATED**, use `cpu_c0_state_residency_percent`) | `cpu_metrics` | `msr` module | +| `cpu_temperature` | `cpu_metrics` | `msr` module | +| `cpu_busy_frequency` | `cpu_metrics` | `msr` module | +| `cpu_c0_substate_c01` | `cpu_metrics` | `perf` interface | +| `cpu_c0_substate_c02` | `cpu_metrics` | `perf` interface | +| `cpu_c0_substate_c0_wait` | `cpu_metrics` | `perf` interface | + +*for all metrics enabled by the configuration option `uncore_frequency`, +starting from kernel version 5.18, only the `intel-uncore-frequency` module +is required. For older kernel versions, the metric `uncore_frequency_mhz_cur` +requires the `msr` module to be enabled. ### Example: Configuration with no per-CPU telemetry @@ -146,167 +367,13 @@ all per-CPU metrics: event_definitions = "/home/telegraf/.cache/pmu-events/GenuineIntel-6-8F-core.json" ``` -## SW Dependencies - -### Kernel modules - -Plugin is mostly based on Linux Kernel modules that expose specific metrics over -`sysfs` or `devfs` interfaces. The following dependencies are expected by -plugin: - -- `intel-rapl` kernel module which exposes Intel Runtime Power Limiting metrics over - `sysfs` (`/sys/devices/virtual/powercap/intel-rapl`), -- `msr` kernel module that provides access to processor model specific - registers over `devfs` (`/dev/cpu/cpu%d/msr`), -- `cpufreq` kernel module - which exposes per-CPU Frequency over `sysfs` - (`/sys/devices/system/cpu/cpu%d/cpufreq/scaling_cur_freq`), -- `intel-uncore-frequency` kernel module exposes Intel uncore frequency metrics - over `sysfs` (`/sys/devices/system/cpu/intel_uncore_frequency`). - -Make sure that required kernel modules are loaded and running. -Modules might have to be manually enabled by using `modprobe`. -Depending on the kernel version, run commands: - -```sh -# rapl modules: -## kernel < 4.0 -sudo modprobe intel_rapl -## kernel >= 4.0 -sudo modprobe rapl -sudo modprobe intel_rapl_common -sudo modprobe intel_rapl_msr - -# msr module: -sudo modprobe msr - -# cpufreq module: -### integrated in kernel - -# intel-uncore-frequency module: -## only for kernel >= 5.6.0 -sudo modprobe intel-uncore-frequency -``` - -### Kernel's perf interface - -For perf-related metrics, when Telegraf is not running as root, -the following capability should be added to the Telegraf executable: - -```sh -sudo setcap cap_sys_admin+ep -``` - -Alternatively, `/proc/sys/kernel/perf_event_paranoid` has to be set to -value less than 1. - -Depending on environment and configuration (number of monitored CPUs -and number of enabled metrics), it might be required to increase -the limit on the number of open file descriptors allowed. -This can be done for example by using `ulimit -n` command. - -### Dependencies of metrics on system configuration - -Details of these dependencies are discussed above: - -| Configuration option | Type | Dependency | -|-------------------------------------------------------------------------------------|-------------------|------------------------------------------------| -| `current_power_consumption` | `package_metrics` | `rapl` kernel module(s) | -| `current_dram_power_consumption` | `package_metrics` | `rapl` kernel module(s) | -| `thermal_design_power` | `package_metrics` | `rapl` kernel module(s) | -| `max_turbo_frequency` | `package_metrics` | `msr` kernel module | -| `uncore_frequency` | `package_metrics` | `intel-uncore-frequency`/`msr` kernel modules* | -| `cpu_base_frequency` | `package_metrics` | `msr` kernel module | -| `cpu_frequency` | `cpu_metrics` | `cpufreq` kernel module | -| `cpu_c0_state_residency` | `cpu_metrics` | `msr` kernel module | -| `cpu_c1_state_residency` | `cpu_metrics` | `msr` kernel module | -| `cpu_c3_state_residency` | `cpu_metrics` | `msr` kernel module | -| `cpu_c6_state_residency` | `cpu_metrics` | `msr` kernel module | -| `cpu_c7_state_residency` | `cpu_metrics` | `msr` kernel module | -| `cpu_busy_cycles` (**DEPRECATED** - superseded by `cpu_c0_state_residency_percent`) | `cpu_metrics` | `msr` kernel module | -| `cpu_temperature` | `cpu_metrics` | `msr` kernel module | -| `cpu_busy_frequency` | `cpu_metrics` | `msr` kernel module | -| `cpu_c0_substate_c01` | `cpu_metrics` | kernel's `perf` interface | -| `cpu_c0_substate_c02` | `cpu_metrics` | kernel's `perf` interface | -| `cpu_c0_substate_c0_wait` | `cpu_metrics` | kernel's `perf` interface | - -*for all metrics enabled by the configuration option `uncore_frequency`, -starting from kernel version 5.18, only the `intel-uncore-frequency` module -is required. For older kernel versions, the metric `uncore_frequency_mhz_cur` -requires the `msr` module to be enabled. - -### Root privileges - -**Telegraf with Intel PowerStat plugin enabled may require -root privileges to read all the metrics** -(depending on OS type or configuration). - -Alternatively, the following capabilities can be added to -the Telegraf executable: - -```sh -#without perf-related metrics: -sudo setcap cap_sys_rawio,cap_dac_read_search+ep - -#with perf-related metrics: -sudo setcap cap_sys_rawio,cap_dac_read_search,cap_sys_admin+ep -``` - -## HW Dependencies - -Specific metrics require certain processor features to be present, otherwise -Intel PowerStat plugin won't be able to read them. The user can detect supported -processor features by reading `/proc/cpuinfo` file. -Plugin assumes crucial properties are the same for all CPU cores in the system. - -The following `processor` properties are examined in more detail -in this section: - -- `vendor_id` -- `cpu family` -- `model` -- `flags` - -The following processor properties are required by the plugin: - -- Processor `vendor_id` must be `GenuineIntel` and `cpu family` must be `6` - - since data used by the plugin are Intel-specific. -- The following processor flags shall be present: - - `msr` shall be present for plugin to read platform data from processor - model specific registers and collect the following metrics: - - `cpu_c0_state_residency` - - `cpu_c1_state_residency` - - `cpu_c3_state_residency` - - `cpu_c6_state_residency` - - `cpu_c7_state_residency` - - `cpu_busy_cycles` (**DEPRECATED** - superseded by `cpu_c0_state_residency_percent`) - - `cpu_busy_frequency` - - `cpu_temperature` - - `cpu_base_frequency` - - `max_turbo_frequency` - - `uncore_frequency` (for kernel < 5.18) - - `aperfmperf` shall be present to collect the following metrics: - - `cpu_c0_state_residency` - - `cpu_c1_state_residency` - - `cpu_busy_cycles` (**DEPRECATED** - superseded by `cpu_c0_state_residency_percent`) - - `cpu_busy_frequency` - - `dts` shall be present to collect: - - `cpu_temperature` -- Please consult the table of [supported CPU models](#supported-cpu-models) to see which metrics are supported by your `model`. The following metrics exist: - - `cpu_c1_state_residency` - - `cpu_c3_state_residency` - - `cpu_c6_state_residency` - - `cpu_c7_state_residency` - - `cpu_temperature` - - `cpu_base_frequency` - - `uncore_frequency` - ## Metrics All metrics collected by Intel PowerStat plugin are collected in fixed intervals. Metrics that reports processor C-state residency or power are calculated over elapsed intervals. -**The following measurements are supported by Intel PowerStat plugin:** +The following measurements are supported by Intel PowerStat plugin: - `powerstat_core` - The following tags are returned by plugin with @@ -409,73 +476,3 @@ powerstat_core,core_id=0,cpu_id=0,host=ubuntu,package_id=0 cpu_c0_substate_c01_p powerstat_core,core_id=0,cpu_id=0,host=ubuntu,package_id=0 cpu_c0_substate_c02_percent=5.68 1606494744000000000 powerstat_core,core_id=0,cpu_id=0,host=ubuntu,package_id=0 cpu_c0_substate_c0_wait_percent=43.74 1606494744000000000 ``` - -## Supported CPU models - -| Model number | Processor name | `cpu_c1_state_residency`
`cpu_c6_state_residency`
`cpu_temperature`
`cpu_base_frequency` | `cpu_c3_state_residency` | `cpu_c7_state_residency` | `uncore_frequency` | -|--------------|---------------------------------|:----------------------------------------------------------------------------------------------------:|:------------------------:|:------------------------:|:------------------:| -| 0x1E | Intel Nehalem | ✓ | ✓ | | | -| 0x1F | Intel Nehalem-G | ✓ | ✓ | | | -| 0x1A | Intel Nehalem-EP | ✓ | ✓ | | | -| 0x2E | Intel Nehalem-EX | ✓ | ✓ | | | -| 0x25 | Intel Westmere | ✓ | ✓ | | | -| 0x2C | Intel Westmere-EP | ✓ | ✓ | | | -| 0x2F | Intel Westmere-EX | ✓ | ✓ | | | -| 0x2A | Intel Sandybridge | ✓ | ✓ | ✓ | | -| 0x2D | Intel Sandybridge-X | ✓ | ✓ | ✓ | | -| 0x3A | Intel Ivybridge | ✓ | ✓ | ✓ | | -| 0x3E | Intel Ivybridge-X | ✓ | ✓ | ✓ | | -| 0x3C | Intel Haswell | ✓ | ✓ | ✓ | | -| 0x3F | Intel Haswell-X | ✓ | ✓ | ✓ | | -| 0x45 | Intel Haswell-L | ✓ | ✓ | ✓ | | -| 0x46 | Intel Haswell-G | ✓ | ✓ | ✓ | | -| 0x3D | Intel Broadwell | ✓ | ✓ | ✓ | | -| 0x47 | Intel Broadwell-G | ✓ | ✓ | ✓ | ✓ | -| 0x4F | Intel Broadwell-X | ✓ | ✓ | | ✓ | -| 0x56 | Intel Broadwell-D | ✓ | ✓ | | ✓ | -| 0x4E | Intel Skylake-L | ✓ | ✓ | ✓ | | -| 0x5E | Intel Skylake | ✓ | ✓ | ✓ | | -| 0x55 | Intel Skylake-X | ✓ | | | ✓ | -| 0x8E | Intel KabyLake-L | ✓ | ✓ | ✓ | | -| 0x9E | Intel KabyLake | ✓ | ✓ | ✓ | | -| 0xA5 | Intel CometLake | ✓ | ✓ | ✓ | | -| 0xA6 | Intel CometLake-L | ✓ | ✓ | ✓ | | -| 0x66 | Intel CannonLake-L | ✓ | | ✓ | | -| 0x6A | Intel IceLake-X | ✓ | | | ✓ | -| 0x6C | Intel IceLake-D | ✓ | | | ✓ | -| 0x7D | Intel IceLake | ✓ | | | | -| 0x7E | Intel IceLake-L | ✓ | | ✓ | | -| 0x9D | Intel IceLake-NNPI | ✓ | | ✓ | | -| 0xA7 | Intel RocketLake | ✓ | | ✓ | | -| 0x8C | Intel TigerLake-L | ✓ | | ✓ | | -| 0x8D | Intel TigerLake | ✓ | | ✓ | | -| 0x8F | Intel Sapphire Rapids X | ✓ | | | ✓ | -| 0xCF | Intel Emerald Rapids X | ✓ | | | ✓ | -| 0xAD | Intel Granite Rapids X | ✓ | | | | -| 0xAE | Intel Granite Rapids D | ✓ | | | | -| 0x8A | Intel Lakefield | ✓ | | ✓ | | -| 0x97 | Intel AlderLake | ✓ | | ✓ | ✓ | -| 0x9A | Intel AlderLake-L | ✓ | | ✓ | ✓ | -| 0xB7 | Intel RaptorLake | ✓ | | ✓ | ✓ | -| 0xBA | Intel RaptorLake-P | ✓ | | ✓ | ✓ | -| 0xBF | Intel RaptorLake-S | ✓ | | ✓ | ✓ | -| 0xAC | Intel MeteorLake | ✓ | | ✓ | ✓ | -| 0xAA | Intel MeteorLake-L | ✓ | | ✓ | ✓ | -| 0xC6 | Intel ArrowLake | ✓ | | ✓ | | -| 0xBD | Intel LunarLake | ✓ | | ✓ | | -| 0x37 | Intel Atom® Bay Trail | ✓ | | | | -| 0x4D | Intel Atom® Avaton | ✓ | | | | -| 0x4A | Intel Atom® Merrifield | ✓ | | | | -| 0x5A | Intel Atom® Moorefield | ✓ | | | | -| 0x4C | Intel Atom® Airmont | ✓ | ✓ | | | -| 0x5C | Intel Atom® Apollo Lake | ✓ | ✓ | ✓ | | -| 0x5F | Intel Atom® Denverton | ✓ | | | | -| 0x7A | Intel Atom® Goldmont | ✓ | ✓ | ✓ | | -| 0x86 | Intel Atom® Jacobsville | ✓ | | | | -| 0x96 | Intel Atom® Elkhart Lake | ✓ | | ✓ | | -| 0x9C | Intel Atom® Jasper Lake | ✓ | | ✓ | | -| 0xBE | Intel AlderLake-N | ✓ | | ✓ | | -| 0xAF | Intel Sierra Forest | ✓ | | | | -| 0xB6 | Intel Grand Ridge | ✓ | | | | -| 0x57 | Intel Xeon® PHI Knights Landing | ✓ | | | | -| 0x85 | Intel Xeon® PHI Knights Mill | ✓ | | | | diff --git a/plugins/inputs/intel_powerstat/sample.conf b/plugins/inputs/intel_powerstat/sample.conf index c7f3089eb..8d3c1a5e8 100644 --- a/plugins/inputs/intel_powerstat/sample.conf +++ b/plugins/inputs/intel_powerstat/sample.conf @@ -27,15 +27,13 @@ ## "cpu_c0_substate_c02", "cpu_c0_substate_c0_wait" # cpu_metrics = [] - ## Optionally the user can choose for which CPUs metrics configured in cpu_metrics array should be gathered. - ## Can't be combined with excluded_cpus. - ## Empty or missing array means CPU metrics are gathered for all CPUs. + ## CPUs metrics to include from those configured in cpu_metrics array + ## Can't be combined with excluded_cpus. Empty means all CPUs are gathered. ## e.g. ["0-3", "4,5,6"] or ["1-3,4"] # included_cpus = [] - ## Optionally the user can choose which CPUs should be excluded from gathering metrics configured in cpu_metrics array. - ## Can't be combined with included_cpus. - ## Empty or missing array means CPU metrics are gathered for all CPUs. + ## CPUs metrics to exclude from those configured in cpu_metrics array + ## Can't be combined with included_cpus. Empty means all CPUs are gathered. ## e.g. ["0-3", "4,5,6"] or ["1-3,4"] # excluded_cpus = [] diff --git a/plugins/inputs/intel_rdt/README.md b/plugins/inputs/intel_rdt/README.md index 3630e4f68..c74efec78 100644 --- a/plugins/inputs/intel_rdt/README.md +++ b/plugins/inputs/intel_rdt/README.md @@ -1,11 +1,9 @@ # Intel RDT Input Plugin -The `intel_rdt` plugin collects information provided by monitoring features of -the Intel Resource Director Technology (Intel(R) RDT). Intel RDT provides the -hardware framework to monitor and control the utilization of shared resources -(ex: last level cache, memory bandwidth). - -## About Intel RDT +This plugin collects information provided by monitoring features of the +[Intel Resource Director Technology][rdt], a hardware framework to monitor and +control the utilization of shared resources (e.g. last level cache, +memory bandwidth). Intel’s Resource Director Technology (RDT) framework consists of: @@ -20,76 +18,30 @@ single-threaded, multithreaded, or complex virtual machine environments. Intel introduces CMT, MBM, CAT and CDP to manage these workloads across shared resources. -## Prerequsities - PQoS Tool +⭐ Telegraf v1.16.0 +🏷️ hardware, system +💻 linux, freebsd, macos -To gather Intel RDT metrics, the `intel_rdt` plugin uses _pqos_ cli tool which -is a part of [Intel(R) RDT Software -Package](https://github.com/intel/intel-cmt-cat). Before using this plugin -please be sure _pqos_ is properly installed and configured regarding that the -plugin run _pqos_ to work with `OS Interface` mode. This plugin supports _pqos_ -version 4.0.0 and above. Note: pqos tool needs root privileges to work -properly. +[rdt]: https://www.intel.com/content/www/us/en/architecture-and-technology/resource-director-technology.html -Metrics will be constantly reported from the following `pqos` commands within -the given interval: +## Requirements -### If telegraf does not run as the root user +The plugin requires the `pqos` cli tool in version 4.0+ to be installed and +configured to work in `OS Interface` mode. The tool is part of the +[Intel(R) RDT Software Package][cmt_cat]. -The `pqos` binary needs to run as root. If telegraf is running as a non-root -user, you may enable sudo to allow `pqos` to run correctly. The `pqos` command -requires root level access to run. There are two options to overcome this if -you run telegraf as a non-root user. +> [!IMPORTANT] +> The `pqos` binary needs to run as root. If telegraf is not running as root +> you need to enable sudo for `pqos` and set the `use_sudo` option to `true`. -It is possible to update the pqos binary with setuid using `chmod u+s -/path/to/pqos`. This approach is simple and requires no modification to the -Telegraf configuration, however pqos is not a read-only tool and there are -security implications for making such a command setuid root. +To setup `pqos` correctly check the [installation guide][install]. For help on +how to configure the tool visit the [wiki][wiki] and read the +[resource control documentation][resctl] -Alternately, you may enable sudo to allow `pqos` to run correctly, as follows: - -Add the following to your sudoers file (assumes telegraf runs as a user named -`telegraf`): - -```sh -telegraf ALL=(ALL) NOPASSWD:/usr/sbin/pqos -r --iface-os --mon-file-type=csv --mon-interval=* -``` - -If you wish to use sudo, you must also add `use_sudo = true` to the Telegraf -configuration (see below). - -### In case of cores monitoring - -```sh -pqos -r --iface-os --mon-file-type=csv --mon-interval=INTERVAL --mon-core=all:[CORES]\;mbt:[CORES] -``` - -where `CORES` is equal to group of cores provided in config. User can provide -many groups. - -### In case of process monitoring - -```sh -pqos -r --iface-os --mon-file-type=csv --mon-interval=INTERVAL --mon-pid=all:[PIDS]\;mbt:[PIDS] -``` - -where `PIDS` is group of processes IDs which name are equal to provided process -name in a config. User can provide many process names which lead to create many -processes groups. - -In both cases `INTERVAL` is equal to sampling_interval from config. - -Because PIDs association within system could change in every moment, Intel RDT -plugin provides a functionality to check on every interval if desired processes -change their PIDs association. If some change is reported, plugin will restart -_pqos_ tool with new arguments. If provided by user process name is not equal to -any of available processes, will be omitted and plugin will constantly check for -process availability. - -## Useful links - -- Pqos installation process: -- Enabling OS interface: , -- More about Intel RDT: +[cmt_cat]: https://github.com/intel/intel-cmt-cat +[install]: https://github.com/intel/intel-cmt-cat/blob/master/INSTALL +[wiki]: https://github.com/intel/intel-cmt-cat/wiki +[resctl]: https://github.com/intel/intel-cmt-cat/wiki/resctrl ## Service Input @@ -145,19 +97,6 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # use_sudo = false ``` -## Metrics - -| Name | Full name | Description | -|---------------|-----------------------------------------------|-------------| -| MBL | Memory Bandwidth on Local NUMA Node | Memory bandwidth utilization by the relevant CPU core/process on the local NUMA memory channel | -| MBR | Memory Bandwidth on Remote NUMA Node | Memory bandwidth utilization by the relevant CPU core/process on the remote NUMA memory channel | -| MBT | Total Memory Bandwidth | Total memory bandwidth utilized by a CPU core/process on local and remote NUMA memory channels | -| LLC | L3 Cache Occupancy | Total Last Level Cache occupancy by a CPU core/process | -| LLC_Misses* | L3 Cache Misses | Total Last Level Cache misses by a CPU core/process | -| IPC* | Instructions Per Cycle | Total instructions per cycle executed by a CPU core/process | - -*optional - ## Troubleshooting Pointing to non-existing cores will lead to throwing an error by _pqos_ and the @@ -178,6 +117,19 @@ pidof PROCESS where `PROCESS` is process name. +## Metrics + +| Name | Full name | Description | +|---------------|-----------------------------------------------|-------------| +| MBL | Memory Bandwidth on Local NUMA Node | Memory bandwidth utilization by the relevant CPU core/process on the local NUMA memory channel | +| MBR | Memory Bandwidth on Remote NUMA Node | Memory bandwidth utilization by the relevant CPU core/process on the remote NUMA memory channel | +| MBT | Total Memory Bandwidth | Total memory bandwidth utilized by a CPU core/process on local and remote NUMA memory channels | +| LLC | L3 Cache Occupancy | Total Last Level Cache occupancy by a CPU core/process | +| LLC_Misses* | L3 Cache Misses | Total Last Level Cache misses by a CPU core/process | +| IPC* | Instructions Per Cycle | Total instructions per cycle executed by a CPU core/process | + +*optional + ## Example Output ```text diff --git a/plugins/inputs/internal/README.md b/plugins/inputs/internal/README.md index 2acb122a0..0a68ff94d 100644 --- a/plugins/inputs/internal/README.md +++ b/plugins/inputs/internal/README.md @@ -1,9 +1,13 @@ # Telegraf Internal Input Plugin -The `internal` plugin collects metrics about the telegraf agent itself. +This plugin collects metrics about the telegraf agent and its plugins. -Note that some metrics are aggregates across all instances of one type of -plugin. +> [!NOTE] +> Some metrics are aggregates across all instances of a plugin type. + +⭐ Telegraf v1.2.0 +🏷️ applications +💻 all ## Global configuration options @@ -29,8 +33,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Metrics -memstats are taken from the Go runtime: - +memstats are collected using the [Go runtime framework][memstats] - internal_memstats - alloc_bytes @@ -85,11 +88,11 @@ plugin and `version=`. - internal_ - individual plugin-specific fields, such as requests counts. -## Tags - All measurements for specific plugins are tagged with information relevant to each particular plugin and with `version=`. +[memstats]: https://golang.org/pkg/runtime/#MemStats + ## Example Output ```text diff --git a/plugins/inputs/internet_speed/README.md b/plugins/inputs/internet_speed/README.md index e9a7d68e5..9f35c8b61 100644 --- a/plugins/inputs/internet_speed/README.md +++ b/plugins/inputs/internet_speed/README.md @@ -1,14 +1,13 @@ # Internet Speed Monitor Input Plugin -The `Internet Speed Monitor` collects data about the internet speed on the -system. +This plugin collects metrics about the internet speed on the system like +download/upload speed, latency etc using the [speedtest.net service][speedtest]. -On some systems, the default settings may cause speed tests to fail; if this -affects you then try enabling `memory_saving_mode`. This reduces the memory -requirements for the test, and may reduce the runtime of the test. However, -please be aware that this may also reduce the accuracy of the test for fast -(>30Mb/s) connections. This setting enables the upstream -[Memory Saving Mode](https://github.com/showwin/speedtest-go#memory-saving-mode) +⭐ Telegraf v1.20.0 +🏷️ network +💻 all + +[speedtest]: https://www.speedtest.net/ ## Global configuration options @@ -60,6 +59,15 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # server_id_include = [] ``` +> [!TIP] +> On some systems, the default settings may cause speed tests to fail. If this +> affects your system, try enabling `memory_saving_mode`, which reduces the +> memory requirements and the runtime of the test at the cost of a reduced +> accuracy especially for fast (>30Mb/s) connections. Check the +> [upstream documentation][docs] for details + +[docs]: https://github.com/showwin/speedtest-go#memory-saving-mode + ## Metrics It collects the following fields: diff --git a/plugins/inputs/interrupts/README.md b/plugins/inputs/interrupts/README.md index f7623ac9a..571572012 100644 --- a/plugins/inputs/interrupts/README.md +++ b/plugins/inputs/interrupts/README.md @@ -1,7 +1,11 @@ # Interrupts Input Plugin -The interrupts plugin gathers metrics about IRQs from `/proc/interrupts` and -`/proc/softirqs`. +This plugin gathers metrics about IRQs from interrupts (`/proc/interrupts`) and +soft-interrupts (`/proc/softirqs`). + +⭐ Telegraf v1.3.0 +🏷️ system +💻 all ## Global configuration options diff --git a/plugins/inputs/ipmi_sensor/README.md b/plugins/inputs/ipmi_sensor/README.md index 41f9fb684..cf0eb27b3 100644 --- a/plugins/inputs/ipmi_sensor/README.md +++ b/plugins/inputs/ipmi_sensor/README.md @@ -1,34 +1,19 @@ # IPMI Sensor Input Plugin -Get bare metal metrics using the command line utility -[`ipmitool`](https://github.com/ipmitool/ipmitool). +This plugin gathers metrics from the +[Intelligent Platform Management Interface][ipmi_spec] using the +[`ipmitool`][ipmitool] command line utility. -If no servers are specified, the plugin will query the local machine sensor -stats via the following command: +> [!IMPORTANT] +> The `ipmitool` requires access to the IPMI device. Please check the +> [permission section](#permissions) for possible solutions. -```sh -ipmitool sdr -``` +⭐ Telegraf v0.12.0 +🏷️ hardware, system +💻 all -or with the version 2 schema: - -```sh -ipmitool sdr elist -``` - -When one or more servers are specified, the plugin will use the following -command to collect remote host sensor stats: - -```sh -ipmitool -I lan -H SERVER -U USERID -P PASSW0RD sdr -``` - -Any of the following parameters will be added to the aforementioned query if -they're configured: - -```sh --y hex_key -L privilege -``` +[ipmi_spec]: https://www.intel.com/content/dam/www/public/us/en/documents/specification-updates/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.pdf +[ipmitool]: https://github.com/ipmitool/ipmitool ## Global configuration options @@ -93,6 +78,33 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # cache_path = "" ``` +If no servers are specified, the plugin will query the local machine sensor +stats via the following command: + +```sh +ipmitool sdr +``` + +or with the version 2 schema: + +```sh +ipmitool sdr elist +``` + +When one or more servers are specified, the plugin will use the following +command to collect remote host sensor stats: + +```sh +ipmitool -I lan -H SERVER -U USERID -P PASSW0RD sdr +``` + +Any of the following parameters will be added to the aforementioned query if +they're configured: + +```sh +-y hex_key -L privilege +``` + ## Sensors By default the plugin collects data via the `sdr` command and returns those diff --git a/plugins/inputs/ipset/README.md b/plugins/inputs/ipset/README.md index 0811bf870..a9eb535bb 100644 --- a/plugins/inputs/ipset/README.md +++ b/plugins/inputs/ipset/README.md @@ -1,48 +1,16 @@ # Ipset Input Plugin -The ipset plugin gathers packets and bytes counters from Linux ipset. -It uses the output of the command "ipset save". -Ipsets created without the "counters" option are ignored. +This plugin gathers packets and bytes counters from [Linux IP sets][ipsets] +using the `ipset` command line tool. -Results are tagged with: +> [!NOTE] +> IP sets created without the "counters" option are ignored. -- ipset name -- ipset entry +⭐ Telegraf v1.6.0 +🏷️ network, system +💻 linux -There are 3 ways to grant telegraf the right to run ipset: - -- Run as root (strongly discouraged) -- Use sudo -- Configure systemd to run telegraf with CAP_NET_ADMIN and CAP_NET_RAW capabilities. - -## Using systemd capabilities - -You may run `systemctl edit telegraf.service` and add the following: - -```text -[Service] -CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN -AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN -``` - -## Using sudo - -You will need the following in your telegraf config: - -```toml -[[inputs.ipset]] - use_sudo = true -``` - -You will also need to update your sudoers file: - -```bash -$ visudo -# Add the following line: -Cmnd_Alias IPSETSAVE = /sbin/ipset save -telegraf ALL=(root) NOPASSWD: IPSETSAVE -Defaults!IPSETSAVE !logfile, !syslog, !pam_session -``` +[ipsets]: https://ipset.netfilter.org/ ## Global configuration options @@ -60,19 +28,69 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. [[inputs.ipset]] ## By default, we only show sets which have already matched at least 1 packet. ## set include_unmatched_sets = true to gather them all. - include_unmatched_sets = false + # include_unmatched_sets = false + ## Adjust your sudo settings appropriately if using this option ("sudo ipset save") ## You can avoid using sudo or root, by setting appropriate privileges for ## the telegraf.service systemd service. - use_sudo = false + # use_sudo = false + ## Add number of entries and number of individual IPs (resolve CIDR syntax) for each ipset - count_per_ip_entries = false + # count_per_ip_entries = false + ## The default timeout of 1s for ipset execution can be overridden here: # timeout = "1s" ``` +### Permissions + +There are 3 ways to grant telegraf the right to run ipset: + +- Run as root (strongly discouraged) +- Use sudo +- Configure systemd to run telegraf with CAP_NET_ADMIN and CAP_NET_RAW + capabilities + +#### Using sudo + +To use sudo set the `use_sudo` option to `true` and update your sudoers file: + +```bash +$ visudo +# Add the following line: +Cmnd_Alias IPSETSAVE = /sbin/ipset save +telegraf ALL=(root) NOPASSWD: IPSETSAVE +Defaults!IPSETSAVE !logfile, !syslog, !pam_session +``` + +#### Using systemd capabilities + +You may run `systemctl edit telegraf.service` and add the following: + +```text +[Service] +CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN +AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN +``` + ## Metrics +- ipset + - tags: + - rule + - set + - fields: + - timeout + - packets + - bytes + +- ipset (for `count_per_ip_entries = true`) + - tags: + - set + - fields: + - entries + - ips + ## Example Output ```sh diff --git a/plugins/inputs/ipset/sample.conf b/plugins/inputs/ipset/sample.conf index 34c6cd92c..0ffa58ca0 100644 --- a/plugins/inputs/ipset/sample.conf +++ b/plugins/inputs/ipset/sample.conf @@ -2,12 +2,15 @@ [[inputs.ipset]] ## By default, we only show sets which have already matched at least 1 packet. ## set include_unmatched_sets = true to gather them all. - include_unmatched_sets = false + # include_unmatched_sets = false + ## Adjust your sudo settings appropriately if using this option ("sudo ipset save") ## You can avoid using sudo or root, by setting appropriate privileges for ## the telegraf.service systemd service. - use_sudo = false + # use_sudo = false + ## Add number of entries and number of individual IPs (resolve CIDR syntax) for each ipset - count_per_ip_entries = false + # count_per_ip_entries = false + ## The default timeout of 1s for ipset execution can be overridden here: # timeout = "1s" diff --git a/plugins/inputs/iptables/README.md b/plugins/inputs/iptables/README.md index 628b72d39..44c596707 100644 --- a/plugins/inputs/iptables/README.md +++ b/plugins/inputs/iptables/README.md @@ -1,67 +1,25 @@ # Iptables Input Plugin -The iptables plugin gathers packets and bytes counters for rules within a set -of table and chain from the Linux's iptables firewall. +This plugin gathers packets and bytes counters for rules within a set of table +and chain from the Linux's iptables firewall. -Rules are identified through associated comment. **Rules without comment are -ignored**. Indeed we need a unique ID for the rule and the rule number is not -a constant: it may vary when rules are inserted/deleted at start-up or by -automatic tools (interactive firewalls, fail2ban, ...). Also when the rule set -is becoming big (hundreds of lines) most people are interested in monitoring -only a small part of the rule set. +> [!IMPORTANT] +> Rules are identified through associated comment, so you must ensure that the +> rules you want to monitor do have a **unique** comment using the `--comment` +> flag when adding them. Rules without comments are ignored. -Before using this plugin **you must ensure that the rules you want to monitor -are named with a unique comment**. Comments are added using the `-m comment ---comment "my comment"` iptables options. +The rule number cannot be used as identifier as it is not constant and +may vary when rules are inserted/deleted at start-up or by automatic tools +(interactive firewalls, fail2ban, ...). -The iptables command requires CAP_NET_ADMIN and CAP_NET_RAW capabilities. You -have several options to grant telegraf to run iptables: +> [!IMPORTANT] +> The `iptables` command requires `CAP_NET_ADMIN` and `CAP_NET_RAW` +> capabilities. Check the [permissions section](#permissions) for ways to +> grant them. -* Run telegraf as root. This is strongly discouraged. -* Configure systemd to run telegraf with CAP_NET_ADMIN and CAP_NET_RAW. This is - the simplest and recommended option. -* Configure sudo to grant telegraf to run iptables. This is the most - restrictive option, but require sudo setup. - -## Using systemd capabilities - -You may run `systemctl edit telegraf.service` and add the following: - -```shell -[Service] -CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN -AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN -``` - -Since telegraf will fork a process to run iptables, `AmbientCapabilities` is -required to transmit the capabilities bounding set to the forked process. - -## Using sudo - -You will need the following in your telegraf config: - -```toml -[[inputs.iptables]] - use_sudo = true -``` - -You will also need to update your sudoers file: - -```bash -$ visudo -# Add the following line: -Cmnd_Alias IPTABLESSHOW = /usr/bin/iptables -nvL * -telegraf ALL=(root) NOPASSWD: IPTABLESSHOW -Defaults!IPTABLESSHOW !logfile, !syslog, !pam_session -``` - -## Using IPtables lock feature - -Defining multiple instances of this plugin in telegraf.conf can lead to -concurrent IPtables access resulting in "ERROR in input [inputs.iptables]: exit -status 4" messages in telegraf.log and missing metrics. Setting 'use_lock = -true' in the plugin configuration will run IPtables with the '-w' switch, -allowing a lock usage to prevent this error. +⭐ Telegraf v1.1.0 +🏷️ network, system +💻 linux ## Global configuration options @@ -83,37 +41,78 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Users must configure sudo to allow telegraf user to run iptables with ## no password. ## iptables can be restricted to only list command "iptables -nvL". - use_sudo = false + # use_sudo = false + ## Setting 'use_lock' to true runs iptables with the "-w" option. ## Adjust your sudo settings appropriately if using this option ## ("iptables -w 5 -nvl") - use_lock = false + # use_lock = false + ## Define an alternate executable, such as "ip6tables". Default is "iptables". # binary = "ip6tables" ## defines the table to monitor: table = "filter" + ## defines the chains to monitor. ## NOTE: iptables rules without a comment will not be monitored. ## Read the plugin documentation for more information. chains = [ "INPUT" ] ``` +### Permissions + +The `iptables` command requires `CAP_NET_ADMIN` and `CAP_NET_RAW capabilities`. +You have several options to grant permissions to telegraf: + +- Run telegraf as root. This is strongly discouraged. +- Configure systemd to run telegraf with CAP_NET_ADMIN and CAP_NET_RAW. This is + the simplest and recommended option. +- Configure sudo to grant telegraf to run iptables. This is the most + restrictive option, but require sudo setup. + +#### Using systemd capabilities + +You may run `systemctl edit telegraf.service` and add the following: + +```shell +[Service] +CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN +AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN +``` + +Since telegraf will fork a process to run iptables, `AmbientCapabilities` is +required to transmit the capabilities bounding set to the forked process. + +#### Using sudo + +To use sudo set the `use_sudo` option to `true` and update your sudoers file: + +```bash +$ visudo +# Add the following line: +Cmnd_Alias IPTABLESSHOW = /usr/bin/iptables -nvL * +telegraf ALL=(root) NOPASSWD: IPTABLESSHOW +Defaults!IPTABLESSHOW !logfile, !syslog, !pam_session +``` + +### Using IPtables lock feature + +Defining multiple instances of this plugin in telegraf.conf can lead to +concurrent IPtables access resulting in "ERROR in input [inputs.iptables]: exit +status 4" messages in telegraf.log and missing metrics. Setting 'use_lock = +true' in the plugin configuration will run IPtables with the '-w' switch, +allowing a lock usage to prevent this error. + ## Metrics -### Measurements & Fields - -* iptables - * pkts (integer, count) - * bytes (integer, bytes) - -### Tags - -* All measurements have the following tags: - * table - * chain - * ruleid - -The `ruleid` is the comment associated to the rule. +- iptables + - tags: + - table + - chain + - ruleid (comment associated to the rule) + - fields: + - pkts (integer, count) + - bytes (integer, bytes) ## Example Output diff --git a/plugins/inputs/iptables/sample.conf b/plugins/inputs/iptables/sample.conf index 5d78d8290..5114faf9b 100644 --- a/plugins/inputs/iptables/sample.conf +++ b/plugins/inputs/iptables/sample.conf @@ -6,15 +6,18 @@ ## Users must configure sudo to allow telegraf user to run iptables with ## no password. ## iptables can be restricted to only list command "iptables -nvL". - use_sudo = false + # use_sudo = false + ## Setting 'use_lock' to true runs iptables with the "-w" option. ## Adjust your sudo settings appropriately if using this option ## ("iptables -w 5 -nvl") - use_lock = false + # use_lock = false + ## Define an alternate executable, such as "ip6tables". Default is "iptables". # binary = "ip6tables" ## defines the table to monitor: table = "filter" + ## defines the chains to monitor. ## NOTE: iptables rules without a comment will not be monitored. ## Read the plugin documentation for more information. diff --git a/plugins/inputs/ipvs/README.md b/plugins/inputs/ipvs/README.md index d9bd05f6d..67643d188 100644 --- a/plugins/inputs/ipvs/README.md +++ b/plugins/inputs/ipvs/README.md @@ -1,9 +1,17 @@ # IPVS Input Plugin -The IPVS input plugin uses the linux kernel netlink socket interface to gather -metrics about ipvs virtual and real servers. +This plugin gathers metrics about the [IPVS virtual and real servers][ipvs] +using the netlink socket interface of the Linux kernel. -**Supported Platforms:** Linux +> [!IMPORTANT] +> The plugin requires `CAP_NET_ADMIN` and `CAP_NET_RAW` capabilities. +> Check the [permissions section](#permissions) for ways to grant them. + +⭐ Telegraf v1.9.0 +🏷️ network, system +💻 linux + +[ipvs]: http://www.linuxvirtualserver.org/software/ipvs.html ## Global configuration options @@ -25,11 +33,21 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ### Permissions -Assuming you installed the telegraf package via one of the published packages, +Assuming you installed the Telegraf package via one of the published packages, the process will be running as the `telegraf` user. However, in order for this -plugin to communicate over netlink sockets it needs the telegraf process to be -running as `root` (or some user with `CAP_NET_ADMIN` and `CAP_NET_RAW`). Be sure -to ensure these permissions before running telegraf with this plugin included. +plugin to communicate over netlink sockets it needs the telegraf process to have +`CAP_NET_ADMIN` and `CAP_NET_RAW` capabilities. + +This is the case when running Telegraf as `root` or some user with +`CAP_NET_ADMIN` and `CAP_NET_RAW`. Alternatively, you can add the capabilities +when starting Telegraf via systemd by running `systemctl edit telegraf.service` +and add the following: + +```shell +[Service] +CapabilityBoundingSet=CAP_NET_RAW CAP_NET_ADMIN +AmbientCapabilities=CAP_NET_RAW CAP_NET_ADMIN +``` ## Metrics