CL-Softwares
/
telegraf
8
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(inputs): Add plugin metadata and update description for g* to i* (#16486)

This commit is contained in:
Sven Rebhan 2025-02-06 22:50:08 +01:00 committed by GitHub
parent c38792949d
commit e839ad17de
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
31 changed files with 876 additions and 826 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
plugins/inputs/github/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

20
plugins/inputs/gnmi/README.md
View File

@ -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 <!-- @/docs/includes/service_input.md -->

18
plugins/inputs/google_cloud_storage/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

24
plugins/inputs/graylog/README.md
View File

@ -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://<host>:9000/api/system/metrics/multiple`) and `namespace`
(e.g. `http://<host>: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://<host>: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 <!-- @/docs/includes/plugin_config.md -->
@ -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

12
plugins/inputs/haproxy/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

27
plugins/inputs/hddtemp/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

13
plugins/inputs/http/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

20
plugins/inputs/http_listener_v2/README.md
View File

@ -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 <!-- @/docs/includes/service_input.md -->
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

7
plugins/inputs/http_response/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

11
plugins/inputs/hugepages/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

11
plugins/inputs/icinga2/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

4
plugins/inputs/infiniband/README.md
View File

@ -6,7 +6,9 @@ system. These are the counters that can be found in
and RDMA counters can be found in
`/sys/class/infiniband/<dev>/ports/<port>/hw_counters/`
**Supported Platforms**: Linux
⭐ Telegraf v1.14.0
🏷️ network
💻 linux
## Global configuration options <!-- @/docs/includes/plugin_config.md -->

74
plugins/inputs/influxdb/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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"
]
```

41
plugins/inputs/influxdb_listener/README.md
View File

@ -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 <!-- @/docs/includes/service_input.md -->
@ -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
```

23
plugins/inputs/influxdb_v2_listener/README.md
View File

@ -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 <!-- @/docs/includes/service_input.md -->
@ -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
```

39
plugins/inputs/intel_baseband/README.md
View File

@ -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:

63
plugins/inputs/intel_dlb/README.md
View File

@ -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

185
plugins/inputs/intel_pmt/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

50
plugins/inputs/intel_pmu/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
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

499
plugins/inputs/intel_powerstat/README.md
View File

@ -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 <path_to_telegraf_binary>
```
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 <path_to_telegraf_binary>
#with perf-related metrics:
sudo setcap cap_sys_rawio,cap_dac_read_search,cap_sys_admin+ep <path_to_telegraf_binary>
```
### 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`<br/>`cpu_c6_state_residency`<br/>`cpu_temperature`<br/>`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 <!-- @/docs/includes/plugin_config.md -->
@ -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 <path_to_telegraf_binary>
```
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 <path_to_telegraf_binary>
#with perf-related metrics:
sudo setcap cap_sys_rawio,cap_dac_read_search,cap_sys_admin+ep <path_to_telegraf_binary>
```
## 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`<br/>`cpu_c6_state_residency`<br/>`cpu_temperature`<br/>`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 | ✓ | | | |

10
plugins/inputs/intel_powerstat/sample.conf
View File

@ -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 = []

118
plugins/inputs/intel_rdt/README.md
View File

@ -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: <https://github.com/intel/intel-cmt-cat/blob/master/INSTALL>
- Enabling OS interface: <https://github.com/intel/intel-cmt-cat/wiki>, <https://github.com/intel/intel-cmt-cat/wiki/resctrl>
- More about Intel RDT: <https://www.intel.com/content/www/us/en/architecture-and-technology/resource-director-technology.html>
[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 <!-- @/docs/includes/service_input.md -->
@ -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

17
plugins/inputs/internal/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -29,8 +33,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
## Metrics
memstats are taken from the Go runtime:
<https://golang.org/pkg/runtime/#MemStats>
memstats are collected using the [Go runtime framework][memstats]
- internal_memstats
- alloc_bytes
@ -85,11 +88,11 @@ plugin and `version=<telegraf_version>`.
- internal_<plugin_name>
- 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=<telegraf_version>`.
[memstats]: https://golang.org/pkg/runtime/#MemStats
## Example Output
```text

24
plugins/inputs/internet_speed/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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:

8
plugins/inputs/interrupts/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->

64
plugins/inputs/ipmi_sensor/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

104
plugins/inputs/ipset/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

9
plugins/inputs/ipset/sample.conf
View File

@ -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"

147
plugins/inputs/iptables/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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

7
plugins/inputs/iptables/sample.conf
View File

@ -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.

32
plugins/inputs/ipvs/README.md
View File

@ -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 <!-- @/docs/includes/plugin_config.md -->
@ -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