diff --git a/plugins/inputs/http/README.md b/plugins/inputs/http/README.md index 4fd50bdb90481..f94917a7b309d 100644 --- a/plugins/inputs/http/README.md +++ b/plugins/inputs/http/README.md @@ -1,6 +1,10 @@ # 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. +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. ## Configuration @@ -75,7 +79,8 @@ The HTTP input plugin collects metrics from one or more HTTP(S) endpoints. The ## Metrics -The metrics collected by this input plugin will depend on the configured `data_format` and the payload returned by the HTTP endpoint(s). +The metrics collected by this input plugin will depend on the configured +`data_format` and the payload returned by the HTTP endpoint(s). The default values below are added if the input format does not specify a value: @@ -85,4 +90,11 @@ The default values below are added if the input format does not specify a value: ## Optional Cookie Authentication Settings -The optional Cookie Authentication Settings will retrieve a cookie from the given authorization endpoint, and use it in subsequent API requests. This is useful for services that do not provide OAuth or Basic Auth authentication, e.g. the [Tesla Powerwall API](https://www.tesla.com/support/energy/powerwall/own/monitoring-from-home-network), which uses a Cookie Auth Body to retrieve an authorization cookie. The Cookie Auth Renewal interval will renew the authorization by retrieving a new cookie at the given interval. +The optional Cookie Authentication Settings will retrieve a cookie from the +given authorization endpoint, and use it in subsequent API requests. This is +useful for services that do not provide OAuth or Basic Auth authentication, +e.g. the [Tesla Powerwall API][tesla], which uses a Cookie Auth Body to retrieve +an authorization cookie. The Cookie Auth Renewal interval will renew the +authorization by retrieving a new cookie at the given interval. + +[tesla]: https://www.tesla.com/support/energy/powerwall/own/monitoring-from-home-network diff --git a/plugins/inputs/http_listener_v2/README.md b/plugins/inputs/http_listener_v2/README.md index bdcfd1fa43abd..fefacae42e9f6 100644 --- a/plugins/inputs/http_listener_v2/README.md +++ b/plugins/inputs/http_listener_v2/README.md @@ -1,18 +1,18 @@ # HTTP Listener v2 Input Plugin 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]. For metrics in -[InfluxDB Line Protocol][line_protocol] it's recommended to use the [`influxdb_listener`][influxdb_listener] -or [`influxdb_v2_listener`][influxdb_v2_listener] instead. +HTTP. Metrics may be sent in any supported [data format][data_format]. For +metrics in [InfluxDB Line Protocol][line_protocol] it's recommended to use the +[`influxdb_listener`][influxdb_listener] or +[`influxdb_v2_listener`][influxdb_v2_listener] instead. **Note:** The plugin previously known as `http_listener` has been renamed `influxdb_listener`. If you would like Telegraf to act as a proxy/relay for -InfluxDB it is recommended to use [`influxdb_listener`][influxdb_listener] or [`influxdb_v2_listener`][influxdb_v2_listener]. +InfluxDB it is recommended to use [`influxdb_listener`][influxdb_listener] or +[`influxdb_v2_listener`][influxdb_v2_listener]. ## Configuration -This is a sample configuration for the plugin. - ```toml @sample.conf # Generic HTTP write listener [[inputs.http_listener_v2]] @@ -68,7 +68,8 @@ This is a sample configuration for the plugin. ## Metrics -Metrics are collected from the part of the request specified by the `data_source` param and are parsed depending on the value of `data_format`. +Metrics are collected from the part of the request specified by the +`data_source` param and are parsed depending on the value of `data_format`. ## Troubleshooting diff --git a/plugins/inputs/http_response/README.md b/plugins/inputs/http_response/README.md index eab8a7101cff5..be74d4d754d10 100644 --- a/plugins/inputs/http_response/README.md +++ b/plugins/inputs/http_response/README.md @@ -96,9 +96,12 @@ This input plugin checks HTTP/HTTPS connections. ### `result` / `result_code` -Upon finishing polling the target server, the plugin registers the result of the operation in the `result` tag, and adds a numeric field called `result_code` corresponding with that tag value. +Upon finishing polling the target server, the plugin registers the result of the +operation in the `result` tag, and adds a numeric field called `result_code` +corresponding with that tag value. -This tag is used to expose network and plugin errors. HTTP errors are considered a successful connection. +This tag is used to expose network and plugin errors. HTTP errors are considered +a successful connection. |Tag value |Corresponding field value|Description| -------------------------------|-------------------------|-----------| diff --git a/plugins/inputs/httpjson/README.md b/plugins/inputs/httpjson/README.md index c0e3a73ca27e7..345cee21df3fd 100644 --- a/plugins/inputs/httpjson/README.md +++ b/plugins/inputs/httpjson/README.md @@ -97,7 +97,9 @@ Given the following response body: The following metric is produced: -`httpjson,server=http://localhost:9999/stats/ b_d=0.1,a=0.5,b_e=5,response_time=0.001` +``` +httpjson,server=http://localhost:9999/stats/ b_d=0.1,a=0.5,b_e=5,response_time=0.001 +``` Note that only numerical values are extracted and the type is float. @@ -110,7 +112,9 @@ If `tag_keys` is included in the configuration: Then the `service` tag will also be added: -`httpjson,server=http://localhost:9999/stats/,service=service01 b_d=0.1,a=0.5,b_e=5,response_time=0.001` +``` +httpjson,server=http://localhost:9999/stats/,service=service01 b_d=0.1,a=0.5,b_e=5,response_time=0.001 +``` **Array Output:** @@ -140,7 +144,9 @@ object: ] ``` -`httpjson,server=http://localhost:9999/stats/,service=service01 a=0.5,b_d=0.1,b_e=5,response_time=0.003` -`httpjson,server=http://localhost:9999/stats/,service=service02 a=0.6,b_d=0.2,b_e=6,response_time=0.003` +``` +httpjson,server=http://localhost:9999/stats/,service=service01 a=0.5,b_d=0.1,b_e=5,response_time=0.003 +httpjson,server=http://localhost:9999/stats/,service=service02 a=0.6,b_d=0.2,b_e=6,response_time=0.003 +``` [HTTP input plugin]: ../http/README.md diff --git a/plugins/inputs/hugepages/README.md b/plugins/inputs/hugepages/README.md index 93535f9fb0c3e..b7cc1f094e302 100644 --- a/plugins/inputs/hugepages/README.md +++ b/plugins/inputs/hugepages/README.md @@ -1,10 +1,11 @@ # Hugepages Input Plugin -Transparent Huge Pages (THP) is a Linux memory management system that reduces the overhead of -Translation Lookaside Buffer (TLB) lookups on machines with large amounts of memory by using larger -memory pages. +Transparent Huge Pages (THP) is a Linux memory management system that reduces +the overhead of Translation Lookaside Buffer (TLB) lookups on machines with +large amounts of memory by using larger memory pages. -Consult for more details. +Consult +for more details. ## Configuration diff --git a/plugins/inputs/icinga2/README.md b/plugins/inputs/icinga2/README.md index 336bdf0cb9a86..0d1fc74122cd7 100644 --- a/plugins/inputs/icinga2/README.md +++ b/plugins/inputs/icinga2/README.md @@ -4,7 +4,9 @@ This plugin gather services & hosts status using Icinga2 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](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api) +[here][1]. + +[1]: https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api ## Configuration diff --git a/plugins/inputs/influxdb/README.md b/plugins/inputs/influxdb/README.md index 76c29dd91fb91..9435e037dfc26 100644 --- a/plugins/inputs/influxdb/README.md +++ b/plugins/inputs/influxdb/README.md @@ -1,12 +1,13 @@ # InfluxDB Input Plugin The InfluxDB plugin will collect metrics on the given InfluxDB servers. Read our -[documentation](https://docs.influxdata.com/platform/monitoring/influxdata-platform/tools/measurements-internal/) -for detailed information about `influxdb` metrics. +[documentation][1] for detailed information about `influxdb` metrics. This plugin can also gather metrics from endpoints that expose InfluxDB-formatted endpoints. See below for more information. +[1]: https://docs.influxdata.com/platform/monitoring/influxdata-platform/tools/measurements-internal/ + ## Configuration ```toml @sample.conf @@ -39,7 +40,8 @@ InfluxDB-formatted endpoints. See below for more information. ## Measurements & Fields -**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. - **bytesRx**: Number of bytes received by the data node. diff --git a/plugins/inputs/influxdb_v2_listener/README.md b/plugins/inputs/influxdb_v2_listener/README.md index 2cf48d529dc4d..0da74db360736 100644 --- a/plugins/inputs/influxdb_v2_listener/README.md +++ b/plugins/inputs/influxdb_v2_listener/README.md @@ -5,9 +5,9 @@ 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. -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. +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 diff --git a/plugins/inputs/intel_pmu/README.md b/plugins/inputs/intel_pmu/README.md index 9d520f0f305d4..659e4fa475cc1 100644 --- a/plugins/inputs/intel_pmu/README.md +++ b/plugins/inputs/intel_pmu/README.md @@ -1,13 +1,18 @@ # 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 input plugin exposes Intel PMU (Performance Monitoring Unit) metrics +available through [Linux Perf](https://perf.wiki.kernel.org/index.php/Main_Page) +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 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. -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. +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. ## Configuration @@ -63,8 +68,10 @@ They form a basis for profiling applications to trace dynamic control flow and i ### Modifiers -Perf modifiers adjust event-specific perf attribute to fulfill particular requirements. -Details about perf attribute structure could be found in [perf_event_open](https://man7.org/linux/man-pages/man2/perf_event_open.2.html) syscall manual. +Perf modifiers adjust event-specific perf attribute to fulfill particular +requirements. Details about perf attribute structure could be found in +[perf_event_open][man] +syscall manual. General schema of configuration's `events` list element: @@ -89,48 +96,65 @@ where: ## 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. +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 [01.org](https://download.01.org/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. +Event definition JSON files for specific architectures can be found at +[01.org](https://download.01.org/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 initialization the event names provided by user are compared -with event definitions included in JSON files and translated to perf attributes. Next, those events are activated to start counting. -During every telegraf interval, the plugin reads proper measurement for each previously activated event. - -Each single core event may be counted severally on every available CPU's core. In contrast, uncore events could be placed in -many PMUs within specified CPU package. The plugin allows choosing core ids (core events) or socket ids (uncore events) on which the counting should be executed. -Uncore events are separately activated on all socket's PMUs, and can be exposed as separate +Plugin allows measuring both core and uncore events. During plugin +initialization the event names provided by user are compared with event +definitions included in JSON files and translated to perf attributes. Next, +those events are activated to start counting. During every telegraf interval, +the plugin reads proper measurement for each previously activated event. + +Each single core event may be counted severally on every available CPU's +core. In contrast, uncore events could be placed in many PMUs within specified +CPU package. The plugin allows choosing core ids (core events) or socket ids +(uncore events) on which the counting should be executed. Uncore events are +separately activated on all socket's PMUs, and can be exposed as separate measurement or to be summed up as one measurement. -Obtained measurements are stored as three values: **Raw**, **Enabled** and **Running**. Raw is a total count of event. Enabled and running are total time the event was enabled and running. -Normally these are the same. If more events are started than available counter slots on the PMU, then multiplexing -occurs and events only run part of the time. Therefore, the plugin provides a 4-th value called **scaled** which is calculated using following formula: -`raw * enabled / running`. +Obtained measurements are stored as three values: **Raw**, **Enabled** and +**Running**. Raw is a total count of event. Enabled and running are total time +the event was enabled and running. Normally these are the same. If more events +are started than available counter slots on the PMU, then multiplexing occurs +and events only run part of the time. Therefore, the plugin provides a 4-th +value called **scaled** which is calculated using following formula: `raw * +enabled / running`. Events are measured for all running processes. ### Core event groups -Perf allows assembling events as a group. A perf event group is scheduled onto the CPU as a unit: it will be put onto the CPU only if all of the events in the group can be put onto the CPU. -This means that the values of the member events can be meaningfully compared — added, divided (to get ratios), and so on — with each other, -since they have counted events for the same set of executed instructions [(source)](https://man7.org/linux/man-pages/man2/perf_event_open.2.html). +Perf allows assembling events as a group. A perf event group is scheduled onto +the CPU as a unit: it will be put onto the CPU only if all of the events in the +group can be put onto the CPU. This means that the values of the member events +can be meaningfully compared — added, divided (to get ratios), and so on — with +each other, since they have counted events for the same set of executed +instructions [(source)][man]. -> **NOTE:** -> Be aware that the plugin will throw an error when trying to create core event group of size that exceeds available core PMU counters. -> The error message from perf syscall will be shown as "invalid argument". If you want to check how many PMUs are supported by your Intel CPU, you can use the [cpuid](https://linux.die.net/man/1/cpuid) command. +> **NOTE:** Be aware that the plugin will throw an error when trying to create +> core event group of size that exceeds available core PMU counters. The error +> message from perf syscall will be shown as "invalid argument". If you want to +> check how many PMUs are supported by your Intel CPU, you can use the +> [cpuid](https://linux.die.net/man/1/cpuid) command. ### Note about file descriptors -The plugin opens a number of file descriptors dependent on number of monitored CPUs and number of monitored -counters. It can easily exceed the default per process limit of allowed file descriptors. Depending on -configuration, it might be required to increase the limit of opened file descriptors allowed. -This can be done for example by using `ulimit -n command`. +The plugin opens a number of file descriptors dependent on number of monitored +CPUs and number of monitored counters. It can easily exceed the default per +process limit of allowed file descriptors. Depending on configuration, it might +be required to increase the limit of opened file descriptors allowed. This can +be done for example by using `ulimit -n command`. ## Metrics @@ -208,3 +232,5 @@ pmu_metric,cpu=0,event=CPU_CLK_UNHALTED.REF_XCLK_ANY,host=xyz enabled=2200963921 pmu_metric,cpu=0,event=L1D_PEND_MISS.PENDING_CYCLES_ANY,host=xyz enabled=2200933946i,running=1470322480i,raw=23631950i,scaled=35374798i 1621254412000000000 pmu_metric,cpu=0,event=L1D_PEND_MISS.PENDING_CYCLES,host=xyz raw=18767833i,scaled=28169827i,enabled=2200888514i,running=1466317384i 1621254412000000000 ``` + +[man]: https://man7.org/linux/man-pages/man2/perf_event_open.2.html diff --git a/plugins/inputs/intel_powerstat/README.md b/plugins/inputs/intel_powerstat/README.md index db84ef73f6fae..eb6b4d86fd780 100644 --- a/plugins/inputs/intel_powerstat/README.md +++ b/plugins/inputs/intel_powerstat/README.md @@ -1,10 +1,13 @@ # Intel PowerStat Input Plugin -This input plugin monitors power statistics on Intel-based platforms and assumes presence of Linux based OS. +This input plugin monitors power statistics on Intel-based platforms and assumes +presence of Linux based OS. -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. +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. ## Configuration @@ -29,7 +32,8 @@ to take preventive/corrective actions based on platform busyness, CPU temperatur ## Example: Configuration with no per-CPU telemetry -This configuration allows getting default processor package specific metrics, no per-CPU metrics are collected: +This configuration allows getting default processor package specific metrics, no +per-CPU metrics are collected: ```toml [[inputs.intel_powerstat]] @@ -38,7 +42,8 @@ This configuration allows getting default processor package specific metrics, no ## Example: Configuration with no per-CPU telemetry - equivalent case -This configuration allows getting default processor package specific metrics, no per-CPU metrics are collected: +This configuration allows getting default processor package specific metrics, no +per-CPU metrics are collected: ```toml [[inputs.intel_powerstat]] @@ -46,7 +51,8 @@ This configuration allows getting default processor package specific metrics, no ## Example: Configuration for CPU Temperature and CPU Frequency -This configuration allows getting default processor package specific metrics, plus subset of per-CPU metrics (CPU Temperature and CPU Frequency): +This configuration allows getting default processor package specific metrics, +plus subset of per-CPU metrics (CPU Temperature and CPU Frequency): ```toml [[inputs.intel_powerstat]] @@ -55,7 +61,8 @@ This configuration allows getting default processor package specific metrics, pl ## Example: Configuration for CPU Temperature and CPU Frequency without default package metrics -This configuration allows getting only a subset of per-CPU metrics (CPU Temperature and CPU Frequency): +This configuration allows getting only a subset of per-CPU metrics (CPU +Temperature and CPU Frequency): ```toml [[inputs.intel_powerstat]] @@ -65,7 +72,8 @@ This configuration allows getting only a subset of per-CPU metrics (CPU Temperat ## Example: Configuration with all available metrics -This configuration allows getting all processor package specific metrics and all per-CPU metrics: +This configuration allows getting all processor package specific metrics and all +per-CPU metrics: ```toml [[inputs.intel_powerstat]] @@ -75,8 +83,9 @@ This configuration allows getting all processor package specific metrics and all ## SW Dependencies -Plugin is based on Linux Kernel modules that expose specific metrics over `sysfs` or `devfs` interfaces. -The following dependencies are expected by plugin: +Plugin is based on Linux Kernel modules that expose specific metrics over +`sysfs` or `devfs` interfaces. The following dependencies are expected by +plugin: - _intel-rapl_ 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`), @@ -84,8 +93,9 @@ The following dependencies are expected by plugin: Minimum kernel version required is 3.13 to satisfy all requirements. -Please make sure that kernel modules are loaded and running (cpufreq is integrated in kernel). Modules might have to be manually enabled by using `modprobe`. -Depending on the kernel version, run commands: +Please make sure that kernel modules are loaded and running (cpufreq is +integrated in kernel). Modules might have to be manually enabled by using +`modprobe`. Depending on the kernel version, run commands: ```sh # kernel 5.x.x: @@ -99,8 +109,9 @@ sudo modprobe msr sudo modprobe intel_rapl ``` -**Telegraf with Intel PowerStat plugin enabled may require root access to read model specific registers (MSRs)** -to retrieve data for calculation of most critical per-CPU specific metrics: +**Telegraf with Intel PowerStat plugin enabled may require root access to read +model specific registers (MSRs)** to retrieve data for calculation of most +critical per-CPU specific metrics: - `cpu_busy_frequency_mhz` - `cpu_temperature_celsius` @@ -112,16 +123,18 @@ and to retrieve data for calculation per-package specific metric: - `max_turbo_frequency_mhz` -To expose other Intel PowerStat metrics root access may or may not be required (depending on OS type or configuration). +To expose other Intel PowerStat metrics root access may or may not be required +(depending on OS type or configuration). ## HW Dependencies -Specific metrics require certain processor features to be present, otherwise Intel PowerStat plugin won't be able to -read them. When using Linux Kernel based OS, user can detect supported processor features reading `/proc/cpuinfo` file. +Specific metrics require certain processor features to be present, otherwise +Intel PowerStat plugin won't be able to read them. When using Linux Kernel based +OS, user can detect supported processor features 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: -processor _cpu family_, _model_ and _flags_. -The following processor properties are required by the plugin: +processor _cpu family_, _model_ and _flags_. The following processor properties +are required by the plugin: - Processor _cpu family_ must be Intel (0x6) - since data used by the plugin assumes Intel specific model specific registers for all features @@ -186,9 +199,11 @@ and _powerstat\_core.cpu\_c6\_state\_residency_ metrics: ## 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. -When starting to measure metrics, plugin skips first iteration of metrics if they are based on deltas with previous value. +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. When starting to measure metrics, plugin +skips first iteration of metrics if they are based on deltas with previous +value. **The following measurements are supported by Intel PowerStat plugin:** @@ -239,18 +254,22 @@ When starting to measure metrics, plugin skips first iteration of metrics if the ### Known issues -From linux kernel version v5.4.77 with [this kernel change](https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/?h=v5.4.77&id=19f6d91bdad42200aac557a683c17b1f65ee6c94) -resources like `/sys/class/powercap/intel-rapl*/*/energy_uj` are readable only by root for security reasons, so this plugin needs root privileges to work properly. +From linux kernel version v5.4.77 with [this kernel change][19f6d91b] resources +like `/sys/class/powercap/intel-rapl*/*/energy_uj` are readable only by root for +security reasons, so this plugin needs root privileges to work properly. -If such strict security restrictions are not relevant, reading permissions to files in `/sys/devices/virtual/powercap/intel-rapl/` -directory can be manually changed for example with `chmod` command with custom parameters. -For example to give all users permission to all files in `intel-rapl` directory: +If such strict security restrictions are not relevant, reading permissions to +files in `/sys/devices/virtual/powercap/intel-rapl/` directory can be manually +changed for example with `chmod` command with custom parameters. For example to +give all users permission to all files in `intel-rapl` directory: ```bash sudo chmod -R a+rx /sys/devices/virtual/powercap/intel-rapl/ ``` -### Example Output +[19f6d91b]: https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/commit/?h=v5.4.77&id=19f6d91bdad42200aac557a683c17b1f65ee6c94 + +## Example Output ```shell powerstat_package,host=ubuntu,package_id=0 thermal_design_power_watts=160 1606494744000000000 diff --git a/plugins/inputs/intel_rdt/README.md b/plugins/inputs/intel_rdt/README.md index a6eaa08393235..66624a2a9d7c1 100644 --- a/plugins/inputs/intel_rdt/README.md +++ b/plugins/inputs/intel_rdt/README.md @@ -1,8 +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). +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 @@ -13,27 +14,31 @@ Intel’s Resource Director Technology (RDT) framework consists of: - Cache Allocation Technology (CAT) - Code and Data Prioritization (CDP) -As multithreaded and multicore platform architectures emerge, the last level cache and -memory bandwidth are key resources to manage for running workloads in single-threaded, -multithreaded, or complex virtual machine environments. Intel introduces CMT, MBM, CAT -and CDP to manage these workloads across shared resources. +As multithreaded and multicore platform architectures emerge, the last level +cache and memory bandwidth are key resources to manage for running workloads in +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 -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. +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. -Metrics will be constantly reported from the following `pqos` commands within the given interval: +Metrics will be constantly reported from the following `pqos` commands within +the given interval: ### If telegraf does not run as the root user -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. +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. 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 @@ -42,7 +47,8 @@ security implications for making such a command setuid root. 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`): +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=* @@ -57,7 +63,8 @@ configuration (see below). 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. +where `CORES` is equal to group of cores provided in config. User can provide +many groups. ### In case of process monitoring @@ -65,22 +72,24 @@ where `CORES` is equal to group of cores provided in config. User can provide ma 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. +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. +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: +* Pqos installation process: +* Enabling OS interface: , +* More about Intel RDT: ## Configuration @@ -130,14 +139,17 @@ More about Intel RDT: +memstats are taken from the Go runtime: + - internal_memstats - alloc_bytes diff --git a/plugins/inputs/internet_speed/README.md b/plugins/inputs/internet_speed/README.md index 63035c4bbc904..ae985acb3a040 100644 --- a/plugins/inputs/internet_speed/README.md +++ b/plugins/inputs/internet_speed/README.md @@ -1,6 +1,7 @@ -# Internet Speed Monitor +# Internet Speed Monitor Input Plugin -The `Internet Speed Monitor` collects data about the internet speed on the system. +The `Internet Speed Monitor` collects data about the internet speed on the +system. ## Configuration diff --git a/plugins/inputs/interrupts/README.md b/plugins/inputs/interrupts/README.md index db61d78af454e..cbebed9773b61 100644 --- a/plugins/inputs/interrupts/README.md +++ b/plugins/inputs/interrupts/README.md @@ -1,6 +1,7 @@ # Interrupts Input Plugin -The interrupts plugin gathers metrics about IRQs from `/proc/interrupts` and `/proc/softirqs`. +The interrupts plugin gathers metrics about IRQs from `/proc/interrupts` and +`/proc/softirqs`. ## Configuration diff --git a/plugins/inputs/ipmi_sensor/README.md b/plugins/inputs/ipmi_sensor/README.md index 2035dd4d53de0..64361950d676a 100644 --- a/plugins/inputs/ipmi_sensor/README.md +++ b/plugins/inputs/ipmi_sensor/README.md @@ -3,7 +3,8 @@ Get bare metal metrics using the command line utility [`ipmitool`](https://github.com/ipmitool/ipmitool). -If no servers are specified, the plugin will query the local machine sensor stats via the following command: +If no servers are specified, the plugin will query the local machine sensor +stats via the following command: ```sh ipmitool sdr @@ -15,13 +16,15 @@ or with the version 2 schema: ipmitool sdr elist ``` -When one or more servers are specified, the plugin will use the following command to collect remote host sensor stats: +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 aformentioned query if they're configured: +Any of the following parameters will be added to the aformentioned query if +they're configured: ```sh -y hex_key -L privilege @@ -114,7 +117,8 @@ ipmi device node. When using udev you can create the device node giving KERNEL=="ipmi*", MODE="660", GROUP="telegraf" ``` -Alternatively, it is possible to use sudo. You will need the following in your telegraf config: +Alternatively, it is possible to use sudo. You will need the following in your +telegraf config: ```toml [[inputs.ipmi_sensor]] diff --git a/plugins/inputs/iptables/README.md b/plugins/inputs/iptables/README.md index 07254ebd8abd3..153162e586dfe 100644 --- a/plugins/inputs/iptables/README.md +++ b/plugins/inputs/iptables/README.md @@ -1,18 +1,27 @@ # 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. +The iptables 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. +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. -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. +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 iptables command requires CAP_NET_ADMIN and CAP_NET_RAW capabilities. You have several options to grant telegraf to run iptables: +The iptables command requires CAP_NET_ADMIN and CAP_NET_RAW capabilities. You +have several options to grant telegraf to run iptables: * 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. +* 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 @@ -47,7 +56,11 @@ 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. +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. ## Configuration diff --git a/plugins/inputs/ipvs/README.md b/plugins/inputs/ipvs/README.md index ccea19690a298..e5779ac907711 100644 --- a/plugins/inputs/ipvs/README.md +++ b/plugins/inputs/ipvs/README.md @@ -77,7 +77,8 @@ ipvs_real_server,address=172.18.64.220,address_family=inet,port=9000,virtual_add ipvs_real_server,address=172.18.64.219,address_family=inet,port=9000,virtual_address=172.18.64.234,virtual_port=9000,virtual_protocol=tcp active_connections=0i,inactive_connections=0i,pps_in=0i,pps_out=0i,connections=0i,pkts_in=0i,pkts_out=0i,bytes_in=0i,bytes_out=0i,cps=0i 1541019340000000000 ``` -Virtual server is configured using `proto+addr+port` and backed by 2 real servers: +Virtual server is configured using `proto+addr+port` and backed by 2 real +servers: ```shell ipvs_virtual_server,address_family=inet,fwmark=47,netmask=32,sched=rr cps=0i,connections=0i,pkts_in=0i,pkts_out=0i,bytes_in=0i,bytes_out=0i,pps_in=0i,pps_out=0i 1541019340000000000