diff --git a/plugins/inputs/jenkins/README.md b/plugins/inputs/jenkins/README.md index 8266754ea..0571e64d8 100644 --- a/plugins/inputs/jenkins/README.md +++ b/plugins/inputs/jenkins/README.md @@ -1,10 +1,14 @@ # Jenkins Input Plugin -The jenkins plugin gathers information about the nodes and jobs running in a -jenkins instance. +This plugin gathers information about the nodes and jobs running in a +[Jenkins][jenkins] instance. The plugin uses the Jenkins API and does not +require a plugin on the server. -This plugin does not require a plugin on jenkins and it makes use of Jenkins API -to retrieve all the information needed. +⭐ Telegraf v1.9.0 +🏷️ applications +💻 all + +[jenkins]: https://www.jenkins.io/ ## Global configuration options diff --git a/plugins/inputs/jolokia2_agent/README.md b/plugins/inputs/jolokia2_agent/README.md index d2039dd3b..591baeb48 100644 --- a/plugins/inputs/jolokia2_agent/README.md +++ b/plugins/inputs/jolokia2_agent/README.md @@ -1,7 +1,13 @@ # Jolokia2 Agent Input Plugin -The `jolokia2_agent` input plugin reads JMX metrics from one or more -[Jolokia agent](https://jolokia.org/agent/jvm.html) REST endpoints. +This plugin reads JMX metrics from one or more [Jolokia agent][jolokia_agent] +REST endpoints. + +⭐ Telegraf v1.5.0 +🏷️ applications, network +💻 all + +[jolokia_agent]: https://jolokia.org/agent/jvm.html ## Global configuration options diff --git a/plugins/inputs/jolokia2_proxy/README.md b/plugins/inputs/jolokia2_proxy/README.md index 2df54ab45..a886771c4 100644 --- a/plugins/inputs/jolokia2_proxy/README.md +++ b/plugins/inputs/jolokia2_proxy/README.md @@ -1,8 +1,13 @@ # Jolokia2 Proxy Input Plugin -The `jolokia2_proxy` input plugin reads JMX metrics from one or more _targets_ -by interacting with a [Jolokia proxy](https://jolokia.org/features/proxy.html) -REST endpoint. +This plugin reads JMX metrics from one or more _targets_ by interacting with a +[Jolokia proxy][jolokia_proxy] REST endpoint. + +⭐ Telegraf v1.5.0 +🏷️ applications, network +💻 all + +[jolokia_proxy]: https://jolokia.org/features/proxy.html ## Global configuration options diff --git a/plugins/inputs/jti_openconfig_telemetry/README.md b/plugins/inputs/jti_openconfig_telemetry/README.md index 3a8a119f9..854115231 100644 --- a/plugins/inputs/jti_openconfig_telemetry/README.md +++ b/plugins/inputs/jti_openconfig_telemetry/README.md @@ -1,11 +1,14 @@ -# JTI OpenConfig Telemetry Input Plugin +# Juniper Telemetry Input Plugin -This plugin reads Juniper Networks implementation of OpenConfig telemetry data -from listed sensors using Junos Telemetry Interface. Refer to -[openconfig.net](http://openconfig.net/) for more details about OpenConfig and -[Junos Telemetry Interface (JTI)][1]. +This service plugin reads [OpenConfig][openconfig] telemetry data via the +[Junos Telemetry Interface (JTI)][jti] from configured from listed sensors. -[1]: https://www.juniper.net/documentation/en_US/junos/topics/concept/junos-telemetry-interface-oveview.html +⭐ Telegraf v1.7.0 +🏷️ network, iot +💻 all + +[openconfig]: http://openconfig.net/ +[jti]: https://www.juniper.net/documentation/en_US/junos/topics/concept/junos-telemetry-interface-oveview.html ## Service Input diff --git a/plugins/inputs/kafka_consumer/README.md b/plugins/inputs/kafka_consumer/README.md index 95b8fd62a..7647c84be 100644 --- a/plugins/inputs/kafka_consumer/README.md +++ b/plugins/inputs/kafka_consumer/README.md @@ -1,7 +1,17 @@ -# Kafka Consumer Input Plugin +# Apache Kafka Consumer Input Plugin -The [Kafka][kafka] consumer plugin reads from Kafka -and creates metrics using one of the supported [input data formats][]. +This service plugin consumes messages from [Kafka brokers][kafka] in one of the +supported [data formats][data_formats]. The plugin uses +[consumer groups][consumer_groups] when talking to the Kafka cluster so multiple +instances of Telegraf can consume messages from the same topic in parallel. + +⭐ Telegraf v0.2.3 +🏷️ messaging +💻 all + +[kafka]: https://kafka.apache.org +[consumer_groups]: http://godoc.org/github.com/wvanbergen/kafka/consumergroup +[data_formats]: /docs/DATA_FORMATS_INPUT.md ## Service Input @@ -214,9 +224,6 @@ to use them. data_format = "influx" ``` -[kafka]: https://kafka.apache.org -[input data formats]: /docs/DATA_FORMATS_INPUT.md - ## Metrics The plugin accepts arbitrary input and parses it according to the `data_format` diff --git a/plugins/inputs/kapacitor/README.md b/plugins/inputs/kapacitor/README.md index 206c1eea5..0328312e1 100644 --- a/plugins/inputs/kapacitor/README.md +++ b/plugins/inputs/kapacitor/README.md @@ -1,6 +1,13 @@ # Kapacitor Input Plugin -The Kapacitor plugin collects metrics from the given Kapacitor instances. +This plugin collects metrics from the configured +[InfluxData Kapacitor][kapacitor] instances. + +⭐ Telegraf v1.3.0 +🏷️ applications +💻 all + +[kapacitor]: https://www.influxdata.com/time-series-platform/kapacitor/ ## Global configuration options diff --git a/plugins/inputs/kernel/README.md b/plugins/inputs/kernel/README.md index 8b53efa3f..64ae5d5e9 100644 --- a/plugins/inputs/kernel/README.md +++ b/plugins/inputs/kernel/README.md @@ -1,68 +1,17 @@ # Kernel Input Plugin -This plugin is only available on Linux. +This plugin gathers metrics about the [Linux kernel][kernel] including, among +others, the [available entropy][entropy], [Kernel Samepage Merging][ksm] and +[Pressure Stall Information][psi]. -The kernel plugin gathers info about the kernel that doesn't fit into other -plugins. In general, it is the statistics available in `/proc/stat` that are not -covered by other plugins as well as the value of -`/proc/sys/kernel/random/entropy_avail` and optionally, Kernel Samepage Merging -and Pressure Stall Information. +⭐ Telegraf v0.11.0 +🏷️ system +💻 linux -The metrics are documented in `man 5 proc` under the `/proc/stat` section, as -well as `man 4 random` under the `/proc interfaces` section -(for `entropy_avail`). - -```text -/proc/sys/kernel/random/entropy_avail -Contains the value of available entropy - -/proc/stat -kernel/system statistics. Varies with architecture. Common entries include: - -page 5741 1808 -The number of pages the system paged in and the number that were paged out (from disk). - -swap 1 0 -The number of swap pages that have been brought in and out. - -intr 1462898 -This line shows counts of interrupts serviced since boot time, for each of -the possible system interrupts. The first column is the total of all -interrupts serviced; each subsequent column is the total for a particular interrupt. - -ctxt 115315 -The number of context switches that the system underwent. - -btime 769041601 -boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). - -processes 86031 -Number of forks since boot. -``` - -Kernel Samepage Merging is generally documented in [kernel documentation][1] and -the available metrics exposed via sysfs are documented in [admin guide][2]. - -Pressure Stall Information is exposed through `/proc/pressure` and is documented -in [kernel documentation][3]. Kernel version 4.20 or later is required. -Examples of PSI: - -```shell -# /proc/pressure/cpu -some avg10=1.53 avg60=1.87 avg300=1.73 total=1088168194 - -# /proc/pressure/memory -some avg10=0.00 avg60=0.00 avg300=0.00 total=3463792 -full avg10=0.00 avg60=0.00 avg300=0.00 total=1429641 - -# /proc/pressure/io -some avg10=0.00 avg60=0.00 avg300=0.00 total=68568296 -full avg10=0.00 avg60=0.00 avg300=0.00 total=54982338 -``` - -[1]: https://www.kernel.org/doc/html/latest/mm/ksm.html -[2]: https://www.kernel.org/doc/html/latest/admin-guide/mm/ksm.html#ksm-daemon-sysfs-interface -[3]: https://www.kernel.org/doc/html/latest/accounting/psi.html +[kernel]: https://kernel.org/ +[entropy]: https://www.kernel.org/doc/html/latest/admin-guide/sysctl/kernel.html#random +[ksm]: https://www.kernel.org/doc/html/latest/mm/ksm.html +[psi]: https://www.kernel.org/doc/html/latest/accounting/psi.html ## Global configuration options @@ -86,6 +35,21 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # collect = [] ``` +Please check the documentation of the underlying kernel interfaces in the +`/proc/stat` section of the [proc man page][man_proc], as well as in the +`/proc interfaces` section of the [random man page][man_random]. + +Kernel Samepage Merging is generally documented in the +[kernel documentation][ksm] and the available metrics exposed via sysfs +are documented in the [admin guide][ksm_admin]. + +Pressure Stall Information is exposed through `/proc/pressure` and is documented +in [kernel documentation][psi]. Kernel version 4.20+ is required. + +[ksm_admin]: https://www.kernel.org/doc/html/latest/admin-guide/mm/ksm.html#ksm-daemon-sysfs-interface +[man_proc]: http://man7.org/linux/man-pages/man5/proc.5.html +[man_random]: https://man7.org/linux/man-pages/man4/random.4.html + ## Metrics - kernel diff --git a/plugins/inputs/kernel_vmstat/README.md b/plugins/inputs/kernel_vmstat/README.md index 32ca67b04..e75ed4fa1 100644 --- a/plugins/inputs/kernel_vmstat/README.md +++ b/plugins/inputs/kernel_vmstat/README.md @@ -1,115 +1,17 @@ -# Kernel VMStat Input Plugin +# Kernel VM Statistics Input Plugin -The kernel_vmstat plugin gathers virtual memory statistics by reading -/proc/vmstat. For a full list of available fields see the /proc/vmstat section -of the [proc man page][man-proc]. For a better idea of what each field -represents, see the [vmstat man page][man-vmstat]. +This plugin gathers virtual memory statistics of the [Linux kernel][kernel] by +reading `/proc/vmstat`. For a full list of available fields check the +`/proc/vmstat` section of the [proc man page][man_proc] and for a detailed +description about the fields see the [vmstat man page][man_vmstat]. -[man-proc]: http://man7.org/linux/man-pages/man5/proc.5.html +⭐ Telegraf v1.0.0 +🏷️ system +💻 linux -[man-vmstat]: http://linux.die.net/man/8/vmstat - -```text -/proc/vmstat -kernel/system statistics. Common entries include (from http://www.linuxinsight.com/proc_vmstat.html): - -Number of pages that are dirty, under writeback or unstable: - -nr_dirty 1550 -nr_writeback 0 -nr_unstable 0 - -Number of pages allocated to page tables, mapped by files or allocated by the kernel slab allocator: - -nr_page_table_pages 699 -nr_mapped 139596 -nr_slab 42723 - -Number of pageins and pageouts (since the last boot): - -pgpgin 33754195 -pgpgout 38985992 - -Number of swapins and swapouts (since the last boot): - -pswpin 2473 -pswpout 2995 - -Number of page allocations per zone (since the last boot): - -pgalloc_high 0 -pgalloc_normal 110123213 -pgalloc_dma32 0 -pgalloc_dma 415219 - -Number of page frees, activations and deactivations (since the last boot): - -pgfree 110549163 -pgactivate 4509729 -pgdeactivate 2136215 - -Number of minor and major page faults (since the last boot): - -pgfault 80663722 -pgmajfault 49813 - -Number of page refills (per zone, since the last boot): - -pgrefill_high 0 -pgrefill_normal 5817500 -pgrefill_dma32 0 -pgrefill_dma 149176 - -Number of page steals (per zone, since the last boot): - -pgsteal_high 0 -pgsteal_normal 10421346 -pgsteal_dma32 0 -pgsteal_dma 142196 - -Number of pages scanned by the kswapd daemon (per zone, since the last boot): - -pgscan_kswapd_high 0 -pgscan_kswapd_normal 10491424 -pgscan_kswapd_dma32 0 -pgscan_kswapd_dma 156130 - -Number of pages reclaimed directly (per zone, since the last boot): - -pgscan_direct_high 0 -pgscan_direct_normal 11904 -pgscan_direct_dma32 0 -pgscan_direct_dma 225 - -Number of pages reclaimed via inode freeing (since the last boot): - -pginodesteal 11 - -Number of slab objects scanned (since the last boot): - -slabs_scanned 8926976 - -Number of pages reclaimed by kswapd (since the last boot): - -kswapd_steal 10551674 - -Number of pages reclaimed by kswapd via inode freeing (since the last boot): - -kswapd_inodesteal 338730 - -Number of kswapd's calls to page reclaim (since the last boot): - -pageoutrun 181908 - -Number of direct reclaim calls (since the last boot): - -allocstall 160 - -Miscellaneous statistics: - -pgrotated 3781 -nr_bounce 0 -``` +[kernel]: https://kernel.org/ +[man_proc]: http://man7.org/linux/man-pages/man5/proc.5.html +[man_vmstat]: https://man7.org/linux/man-pages/man8/vmstat.8.html ## Global configuration options diff --git a/plugins/inputs/kibana/README.md b/plugins/inputs/kibana/README.md index ca2c19478..a333daf87 100644 --- a/plugins/inputs/kibana/README.md +++ b/plugins/inputs/kibana/README.md @@ -1,11 +1,16 @@ # Kibana Input Plugin -The `kibana` plugin queries the [Kibana][] API to obtain the service status. +This plugin collects metrics about service status from [Kibana][kibana] +instances via the server's API. -- Telegraf minimum version: 1.8 -- Kibana minimum tested version: 6.0 +> [!NOTE] +> This plugin requires Kibana version 6.0+. -[Kibana]: https://www.elastic.co/ +⭐ Telegraf v1.8.0 +🏷️ applications, server +💻 all + +[kibana]: https://www.elastic.co/kibana ## Global configuration options @@ -37,7 +42,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # tls_key = "/etc/telegraf/key.pem" ## Use TLS but skip chain & host verification # insecure_skip_verify = false - + ## If 'use_system_proxy' is set to true, Telegraf will check env vars such as ## HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or their lowercase counterparts). ## If 'use_system_proxy' is set to false (default) and 'http_proxy_url' is diff --git a/plugins/inputs/kibana/sample.conf b/plugins/inputs/kibana/sample.conf index 3d58a311a..d43614f30 100644 --- a/plugins/inputs/kibana/sample.conf +++ b/plugins/inputs/kibana/sample.conf @@ -16,7 +16,7 @@ # tls_key = "/etc/telegraf/key.pem" ## Use TLS but skip chain & host verification # insecure_skip_verify = false - + ## If 'use_system_proxy' is set to true, Telegraf will check env vars such as ## HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or their lowercase counterparts). ## If 'use_system_proxy' is set to false (default) and 'http_proxy_url' is diff --git a/plugins/inputs/kinesis_consumer/README.md b/plugins/inputs/kinesis_consumer/README.md index 86efc1515..770ecc59b 100644 --- a/plugins/inputs/kinesis_consumer/README.md +++ b/plugins/inputs/kinesis_consumer/README.md @@ -1,7 +1,11 @@ # Kinesis Consumer Input Plugin -This plugin consumes records from [AWS Kinesis][kinesis] data stream and -creates metrics using one of the supported [data formats][data_formats]. +This service input plugin consumes messages from [AWS Kinesis][kinesis] data +stream in one of the supported [data formats][data_formats]. + +⭐ Telegraf v1.10.0 +🏷️ messaging, iot +💻 all [kinesis]: https://aws.amazon.com/kinesis/ [data_formats]: /docs/DATA_FORMATS_INPUT.md @@ -130,4 +134,9 @@ Sort key: shard_id ## Metrics +The plugin accepts arbitrary input and parses it according to the `data_format` +setting. There is no predefined metric format. + ## Example Output + +There is no predefined metric format, so output depends on plugin input. diff --git a/plugins/inputs/knx_listener/README.md b/plugins/inputs/knx_listener/README.md index ac38e191b..cf2e0367e 100644 --- a/plugins/inputs/knx_listener/README.md +++ b/plugins/inputs/knx_listener/README.md @@ -1,9 +1,15 @@ # KNX Input Plugin -The KNX input plugin that listens for messages on the KNX home-automation bus. -This plugin connects to the KNX bus via a KNX-IP interface. -Information about supported KNX message datapoint types can be found at the -underlying "knx-go" project site (). +This service plugin listens for messages on the [KNX home-automation bus][knx] +by connecting via a KNX-IP interface. Information about supported KNX +datapoint-types can be found at the underlying [`knx-go` project][knxgo]. + +⭐ Telegraf v1.19.0 +🏷️ iot +💻 all + +[knx]: https://www.knx.org +[knxgo]: https://github.com/vapourismo/knx-go> ## Service Input @@ -57,7 +63,10 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ### Related tools -- [knx-telegraf-config-generator](https://github.com/svsool/knx-telegraf-config-generator) generates configuration from KNX project file +- [knx-telegraf-config-generator][knx_config_generator]: generates a Telegraf + configuration from a KNX project file + +[knx_config_generator]: https://github.com/svsool/knx-telegraf-config-generator ### Measurement configurations @@ -66,7 +75,8 @@ addresses to this measurement. You can, for example group all temperature sensor messages within a "temperature" measurement. However, you are free to split messages of one datapoint-type to multiple measurements. -**NOTE: You should not assign a group-address (GA) to multiple measurements!** +> [!IMPORTANT] +> You should not assign a group-address (GA) to multiple measurements! ## Metrics @@ -74,9 +84,9 @@ Received KNX data is stored in the named measurement as configured above using the "value" field. Additional to the value, there are the following tags added to the datapoint: -- "groupaddress": KNX group-address corresponding to the value -- "unit": unit of the value -- "source": KNX physical address sending the value +- `groupaddress`: KNX group-address corresponding to the value +- `unit`: unit of the value +- `source`: KNX physical address sending the value To find out about the datatype of the datapoint please check your KNX project, the KNX-specification or the "knx-go" project for the corresponding DPT. diff --git a/plugins/inputs/kube_inventory/README.md b/plugins/inputs/kube_inventory/README.md index 70ebf6fa5..9f3f5e2ac 100644 --- a/plugins/inputs/kube_inventory/README.md +++ b/plugins/inputs/kube_inventory/README.md @@ -1,38 +1,24 @@ # Kubernetes Inventory Input Plugin -This plugin generates metrics derived from the state of the following -Kubernetes resources: +This plugin gathers metrics from [Kubernetes][kubernetes] resources. -- daemonsets -- deployments -- endpoints -- ingress -- nodes -- persistentvolumes -- persistentvolumeclaims -- pods (containers) -- services -- statefulsets -- resourcequotas +> [!NOTE] +> This plugin requires Kubernetes version 1.11+. -Kubernetes is a fast moving project, with a new minor release every 3 months. -As such, we will aim to maintain support only for versions that are supported -by the major cloud providers; this is roughly 4 release / 2 years. +The gathered resources include for example daemon sets, deployments, endpoints, +ingress, nodes, persistent volumes and many more. -**This plugin supports Kubernetes 1.11 and later.** +> [!CRITICAL] +> This plugin produces high cardinality data, which when not controlled for will +> cause high load on your database. Please make sure to [filter][filtering] the +> produced metrics or configure your database to avoid cardinality issues! -## Series Cardinality Warning +⭐ Telegraf v1.10.0 +🏷️ containers +💻 all -This plugin may produce a high number of series which, when not controlled -for, will cause high load on your database. Use the following techniques to -avoid cardinality issues: - -- Use [metric filtering][] options to exclude unneeded measurements and tags. -- Write to a database with an appropriate [retention policy][]. -- Consider using the [Time Series Index][tsi]. -- Monitor your databases [series cardinality][]. -- Consult the [InfluxDB documentation][influx-docs] for the most up-to-date - techniques. +[kubernetes]: https://kubernetes.io/ +[filtering]: /docs/CONFIGURATION.md#metric-filtering ## Global configuration options @@ -411,9 +397,3 @@ kubernetes_pod_container,condition=Ready,host=vjain,pod_name=uefi-5997f76f69-xzl kubernetes_pod_container,container_name=telegraf,namespace=default,node_name=ip-172-17-0-2.internal,node_selector_node-role.kubernetes.io/compute=true,pod_name=tick1,phase=Running,state=running,readiness=ready resource_requests_cpu_units=0.1,resource_limits_memory_bytes=524288000,resource_limits_cpu_units=0.5,restarts_total=0i,state_code=0i,state_reason="",phase_reason="",resource_requests_memory_bytes=524288000 1547597616000000000 kubernetes_statefulset,namespace=default,selector_select1=s1,statefulset_name=etcd replicas_updated=3i,spec_replicas=3i,observed_generation=1i,created=1544101669000000000i,generation=1i,replicas=3i,replicas_current=3i,replicas_ready=3i 1547597616000000000 ``` - -[metric filtering]: https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md#metric-filtering -[retention policy]: https://docs.influxdata.com/influxdb/latest/guides/downsampling_and_retention/ -[tsi]: https://docs.influxdata.com/influxdb/latest/concepts/time-series-index/ -[series cardinality]: https://docs.influxdata.com/influxdb/latest/query_language/spec/#show-cardinality -[influx-docs]: https://docs.influxdata.com/influxdb/latest/ diff --git a/plugins/inputs/kubernetes/README.md b/plugins/inputs/kubernetes/README.md index 5ac9ef287..123a5e70e 100644 --- a/plugins/inputs/kubernetes/README.md +++ b/plugins/inputs/kubernetes/README.md @@ -1,44 +1,25 @@ # Kubernetes Input Plugin -The Kubernetes plugin talks to the Kubelet API and gathers metrics about the -running pods and containers for a single host. It is assumed that this plugin -is running as part of a `daemonset` within a kubernetes installation. This -means that telegraf is running on every node within the cluster. Therefore, you -should configure this plugin to talk to its locally running kubelet. +This plugin gathers metrics about running pods and containers of a +[Kubernetes][kubernetes] instance via the Kubelet API. -Kubernetes is a fast moving project, with a new minor release every 3 months. As -such, this plugin aims to maintain support only for versions that are supported -by the major cloud providers, namely, 4 release over 2 years. +> [!NOTE] +> This plugin has to run as part of a `daemonset` within a Kubernetes +> installation, i.e. Telegraf is running on every node within the cluster. -## Host IP +You should configure this plugin to talk to its locally running kubelet. -To find the ip address of the host you are running on you can issue a command -like the following: +> [!CRITICAL] +> This plugin produces high cardinality data, which when not controlled for will +> cause high load on your database. Please make sure to [filter][filtering] the +> produced metrics or configure your database to avoid cardinality issues! -```sh -curl -s $API_URL/api/v1/namespaces/$POD_NAMESPACE/pods/$HOSTNAME \ - --header "Authorization: Bearer $TOKEN" \ - --insecure | jq -r '.status.hostIP' -``` +⭐ Telegraf v1.1.0 +🏷️ containers +💻 all -This example uses the downward API to pass in the `$POD_NAMESPACE` and -`$HOSTNAME` is the hostname of the pod which is set by the kubernetes API. -See the [Kubernetes docs][] for a full example of generating a bearer token to -explore the Kubernetes API. - -[Kubernetes docs]: https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#without-kubectl-proxy - -## Series Cardinality Warning - -This plugin may produce a high number of series which, when not controlled -for, will cause high load on your database. Use the following techniques to -avoid cardinality issues: - -- Use [metric filtering][] options to exclude unneeded measurements and tags. -- Write to a database with an appropriate [retention policy][]. -- Consider using the [Time Series Index][tsi]. -- Monitor your databases [series cardinality][]. -- Consult the [InfluxDB documentation][influx-docs] for the most up-to-date techniques. +[kubernetes]: https://kubernetes.io/ +[filtering]: /docs/CONFIGURATION.md#metric-filtering ## Global configuration options @@ -90,15 +71,40 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # insecure_skip_verify = false ``` -## DaemonSet +### Host IP -For recommendations on running Telegraf as a DaemonSet see [Monitoring -Kubernetes Architecture][k8s-telegraf] or view the Helm charts: +To find the ip address of the host you are running on you can issue a command +like the following: -- [Telegraf][] -- [InfluxDB][] -- [Chronograf][] -- [Kapacitor][] +```sh +curl -s $API_URL/api/v1/namespaces/$POD_NAMESPACE/pods/$HOSTNAME \ + --header "Authorization: Bearer $TOKEN" \ + --insecure | jq -r '.status.hostIP' +``` + +This example uses the downward API to pass in the `$POD_NAMESPACE` and +`$HOSTNAME` is the hostname of the pod which is set by the kubernetes API. +See the [Kubernetes documentation][Kubernetes_docs] for a full example of +generating a bearer token to explore the Kubernetes API. + +[Kubernetes_docs]: https://kubernetes.io/docs/tasks/administer-cluster/access-cluster-api/#without-kubectl-proxy + +### Daemon-set + +For recommendations on running Telegraf as a daemon-set see the +[Monitoring Kubernetes Architecture blog post][k8s_telegraf_blog] or check the +following Helm charts: + +- [Telegraf][helm_telegraf] +- [InfluxDB][helm_influxdb] +- [Chronograf][helm_chronograf] +- [Kapacitor][helm_kapacitor] + +[k8s_telegraf_blog]: https://www.influxdata.com/blog/monitoring-kubernetes-architecture/ +[helm_telegraf]: https://github.com/helm/charts/tree/master/stable/telegraf +[helm_influxdb]: https://github.com/helm/charts/tree/master/stable/influxdb +[helm_chronograf]: https://github.com/helm/charts/tree/master/stable/chronograf +[helm_kapacitor]: https://github.com/helm/charts/tree/master/stable/kapacitor ## Metrics @@ -177,14 +183,3 @@ kubernetes_pod_network,namespace=deis,node_name=ip-10-0-0-0.ec2.internal,pod_nam kubernetes_pod_volume,volume_name=default-token-f7wts,namespace=default,node_name=ip-172-17-0-1.internal,pod_name=storage-7 available_bytes=8415240192i,capacity_bytes=8415252480i,used_bytes=12288i 1546910783000000000 kubernetes_system_container ``` - -[metric filtering]: https://github.com/influxdata/telegraf/blob/master/docs/CONFIGURATION.md#metric-filtering -[retention policy]: https://docs.influxdata.com/influxdb/latest/guides/downsampling_and_retention/ -[tsi]: https://docs.influxdata.com/influxdb/latest/concepts/time-series-index/ -[series cardinality]: https://docs.influxdata.com/influxdb/latest/query_language/spec/#show-cardinality -[influx-docs]: https://docs.influxdata.com/influxdb/latest/ -[k8s-telegraf]: https://www.influxdata.com/blog/monitoring-kubernetes-architecture/ -[telegraf]: https://github.com/helm/charts/tree/master/stable/telegraf -[influxdb]: https://github.com/helm/charts/tree/master/stable/influxdb -[chronograf]: https://github.com/helm/charts/tree/master/stable/chronograf -[kapacitor]: https://github.com/helm/charts/tree/master/stable/kapacitor diff --git a/plugins/inputs/lanz/README.md b/plugins/inputs/lanz/README.md index ad4e3e08b..803af0796 100644 --- a/plugins/inputs/lanz/README.md +++ b/plugins/inputs/lanz/README.md @@ -1,17 +1,19 @@ # Arista LANZ Consumer Input Plugin -This plugin provides a consumer for use with Arista Networks’ Latency Analyzer -(LANZ) +This service plugin consumes messages from the +[Arista Networks’ Latency Analyzer (LANZ)][lanz] by receiving the datastream +on TCP (usually through port 50001) on the switch's management IP. -Metrics are read from a stream of data via TCP through port 50001 on the -switches management IP. The data is in Protobuffers format. For more information -on Arista LANZ +> [!NOTE] +> You will need to configure LANZ and enable streaming LANZ data, see the +> [documentation][config_lanz] for more details. -- +⭐ Telegraf v1.14.0 +🏷️ network +💻 all -This plugin uses Arista's sdk. - -- +[lanz]: https://www.arista.com/en/um-eos/eos-latency-analyzer-lanz +[config_lanz]: https://www.arista.com/en/um-eos/eos-section-44-3-configuring-lanz ## Service Input @@ -45,15 +47,9 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ] ``` -You will need to configure LANZ and enable streaming LANZ data. - -- -- - ## Metrics -For more details on the metrics see - +For more details on the metrics see the [protocol buffer definition][proto]. - lanz_congestion_record: - tags: @@ -82,6 +78,8 @@ For more details on the metrics see - buffer_size (integer) - duration (integer) +[proto]: https://github.com/aristanetworks/goarista/blob/master/lanz/proto/lanz.proto + ## Sample Queries Get the max tx_latency for the last hour for all interfaces on all switches. diff --git a/plugins/inputs/ldap/README.md b/plugins/inputs/ldap/README.md index 68c740dde..695c592e6 100644 --- a/plugins/inputs/ldap/README.md +++ b/plugins/inputs/ldap/README.md @@ -1,8 +1,15 @@ # LDAP Input Plugin This plugin gathers metrics from LDAP servers' monitoring (`cn=Monitor`) -backend. Currently this plugin supports [OpenLDAP](https://www.openldap.org/) -and [389ds](https://www.port389.org/) servers. +backend. Currently this plugin supports [OpenLDAP][openldap] and [389ds][389ds] +servers. + +⭐ Telegraf v1.29.0 +🏷️ network, server +💻 all + +[openldap]: https://www.openldap.org/ +[389ds]: https://www.port389.org/ ## Global configuration options @@ -66,9 +73,10 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ``` To use this plugin you must enable the monitoring backend/plugin of your LDAP -server. See -[OpenLDAP](https://www.openldap.org/devel/admin/monitoringslapd.html) or 389ds -documentation for details. +server. See [OpenLDAP][openldap_monitoring] or [389ds][389ds] documentation for +details. + +[openldap_monitoring]: https://www.openldap.org/devel/admin/monitoringslapd.html ## Metrics diff --git a/plugins/inputs/leofs/README.md b/plugins/inputs/leofs/README.md index 3afee0f71..abc21510d 100644 --- a/plugins/inputs/leofs/README.md +++ b/plugins/inputs/leofs/README.md @@ -1,8 +1,15 @@ # LeoFS Input Plugin -The LeoFS plugin gathers metrics of LeoGateway, LeoManager, and LeoStorage using -SNMP. See [LeoFS Documentation / System Administration / System -Monitoring](https://leo-project.net/leofs/docs/admin/system_admin/monitoring/). +This plugin gathers metrics of the [LEO filesystem][leofs] services +_LeoGateway_, _LeoManager_, and _LeoStorage_ via SNMP. Check the +[LeoFS system monitoring documentation][docs] for details. + +⭐ Telegraf v0.1.5 +🏷️ network, server +💻 all + +[leofs]: https://leo-project.net/leofs/ +[docs]: https://leo-project.net/leofs/docs/admin/system_admin/monitoring/ ## Global configuration options diff --git a/plugins/inputs/libvirt/README.md b/plugins/inputs/libvirt/README.md index 9bd7f43a9..35eb274eb 100644 --- a/plugins/inputs/libvirt/README.md +++ b/plugins/inputs/libvirt/README.md @@ -1,26 +1,26 @@ # Libvirt Input Plugin -The `libvirt` plugin collects statistics about virtualized -guests on a system by using virtualization libvirt API, -created by RedHat's Emerging Technology group. -Metrics are gathered directly from the hypervisor on a host -system, which means that Telegraf doesn't have to be installed -and configured on a guest system. +This plugin collects statistics about virtualized guests on a system by using +the [libvirt][libvirt] virtualization API. Metrics are gathered directly from +the hypervisor on a host system, so Telegraf doesn't have to be installed and +configured on a guest system. -## Prerequisites +⭐ Telegraf v1.25.0 +🏷️ server +💻 all -For proper operation of the libvirt plugin, -it is required that the host system has: +[libvirt]: https://libvirt.org/ + +## Requirements + +For proper operation of the plugin, it is required that the host system has: - enabled virtualization options for host CPU - libvirtd and its dependencies installed and running -- qemu hypervisor installed and running +- [qemu hypervisor][qemu] installed and running - at least one virtual machine for statistics monitoring -Useful links: - -- [libvirt](https://libvirt.org/) -- [qemu](https://www.qemu.org/) +[qemu]: https://www.qemu.org/ ## Global configuration options diff --git a/plugins/inputs/linux_cpu/README.md b/plugins/inputs/linux_cpu/README.md index 60bc1c0df..325c37287 100644 --- a/plugins/inputs/linux_cpu/README.md +++ b/plugins/inputs/linux_cpu/README.md @@ -1,6 +1,12 @@ # Linux CPU Input Plugin -The `linux_cpu` plugin gathers CPU metrics exposed on Linux-based systems. +This plugin gathers CPU metrics exposed on [Linux][kernel] systems. + +⭐ Telegraf v1.24.0 +🏷️ system +💻 linux + +[kernel]: https://kernel.org/ ## Global configuration options diff --git a/plugins/inputs/linux_sysctl_fs/README.md b/plugins/inputs/linux_sysctl_fs/README.md index 3af0bb58d..199d12b8b 100644 --- a/plugins/inputs/linux_sysctl_fs/README.md +++ b/plugins/inputs/linux_sysctl_fs/README.md @@ -1,14 +1,14 @@ -# Linux Sysctl FS Input Plugin +# Linux Sysctl Filesystem Input Plugin -The linux_sysctl_fs input provides Linux system level file metrics. The -documentation on these fields can be found at -. +This plugin gathers metrics by reading the [system filesystem][sysfs] files on +[Linux][kernel] systems. -Example output: +⭐ Telegraf v1.24.0 +🏷️ system +💻 linux -```shell -> linux_sysctl_fs,host=foo dentry-want-pages=0i,file-max=44222i,aio-max-nr=65536i,inode-preshrink-nr=0i,dentry-nr=64340i,dentry-unused-nr=55274i,file-nr=1568i,aio-nr=0i,inode-nr=35952i,inode-free-nr=12957i,dentry-age-limit=45i 1490982022000000000 -``` +[kernel]: https://kernel.org/ +[sysfs]: https://www.kernel.org/doc/Documentation/sysctl/fs.txt ## Global configuration options @@ -29,4 +29,28 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Metrics +`linux_sysctl_fs` metric: + +- tags: _none_ +- fields: + - `aio-max-nr` (unsigned integer) + - `aio-nr` (unsigned integer) + - `dentry-age-limit` (unsigned integer) + - `dentry-nr` (unsigned integer) + - `dentry-unused-nr` (unsigned integer) + - `dentry-want-pages` (unsigned integer) + - `dquot-max` (unsigned integer) + - `dquot-nr` (unsigned integer) + - `inode-free-nr` (unsigned integer) + - `inode-nr` (unsigned integer) + - `inode-preshrink-nr` (unsigned integer) + - `super-max` (unsigned integer) + - `super-nr` (unsigned integer) + - `file-max` (unsigned integer) + - `file-nr` (unsigned integer) + ## Example Output + +```text +> linux_sysctl_fs,host=foo dentry-want-pages=0i,file-max=44222i,aio-max-nr=65536i,inode-preshrink-nr=0i,dentry-nr=64340i,dentry-unused-nr=55274i,file-nr=1568i,aio-nr=0i,inode-nr=35952i,inode-free-nr=12957i,dentry-age-limit=45i 1490982022000000000 +``` diff --git a/plugins/inputs/logparser/README.md b/plugins/inputs/logparser/README.md index 6e9a40644..fa385459c 100644 --- a/plugins/inputs/logparser/README.md +++ b/plugins/inputs/logparser/README.md @@ -1,26 +1,26 @@ # Logparser Input Plugin -**Deprecated in Telegraf 1.15: Please use the [tail][] plugin along with the -[`grok` data format][grok parser]** - -The `logparser` plugin streams and parses the given logfiles. Currently it +This service plugin streams and parses the given logfiles. Currently it has the capability of parsing "grok" patterns from logfiles, which also supports regex patterns. -The `tail` plugin now provides all the functionality of the `logparser` plugin. -Most options can be translated directly to the `tail` plugin: +> [!IMPORTANT] +> This plugin is deprecated. Please use the [`tail` plugin][tail] plugin in +> combination with the [`grok` data format][grok_parser] as a replacement. -- For options in the `[inputs.logparser.grok]` section, the equivalent option - will have add the `grok_` prefix when using them in the `tail` input. -- The grok `measurement` option can be replaced using the standard plugin - `name_override` option. +⭐ Telegraf v1.0.0 +🚩 Telegraf v1.15.0 +🔥 Telegraf v1.35.0 +🏷️ system, logging +💻 freebsd, linux, macos, windows -This plugin also supports [metric filtering](CONFIGURATION.md#metric-filtering) -and some [additional common options](CONFIGURATION.md#processor-plugins). +## Migration guide -## Example +This plugin is deprecated since Telegraf v1.15. To replace the plugin please +use the [`tail` plugin][tail] plugin in combination with the +[`grok` data format][grok_parser]. -Migration Example: +Here an example for replacing the existing instance: ```diff - [[inputs.logparser]] @@ -46,6 +46,9 @@ Migration Example: + data_format = "grok" ``` +[tail]: /plugins/inputs/tail/README.md +[grok_parser]: /plugins/parsers/grok/README.md + ## Service Input This plugin is a service input. Normal plugins gather metrics determined by the @@ -123,18 +126,11 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # unique_timestamp = "auto" ``` -## Grok Parser - -Reference the [grok parser][] documentation to setup the grok section of the -configuration. - -## Additional Resources - -- - -[tail]: /plugins/inputs/tail/README.md -[grok parser]: /plugins/parsers/grok/README.md - ## Metrics +The plugin accepts arbitrary input and parses it according to the `grok` +patterns configured. There is no predefined metric format. + ## Example Output + +There is no predefined metric format, so output depends on plugin input. diff --git a/plugins/inputs/logstash/README.md b/plugins/inputs/logstash/README.md index 581701dcb..79c3e841a 100644 --- a/plugins/inputs/logstash/README.md +++ b/plugins/inputs/logstash/README.md @@ -1,9 +1,17 @@ # Logstash Input Plugin -This plugin reads metrics exposed by [Logstash Monitoring -API](https://www.elastic.co/guide/en/logstash/current/monitoring-logstash.html). +This plugin gathers metrics from a [Logstash][logstash] endpoint using the +[Monitoring API][logstash_api]. -Logstash 5 and later is supported. +> [!NOTE] +> This plugin supports Logstash 5+. + +⭐ Telegraf v1.12.0 +🏷️ server +💻 all + +[logstash]: https://www.elastic.co/logstash +[logstash_api]: https://www.elastic.co/guide/en/logstash/current/monitoring-logstash.html ## Global configuration options @@ -44,7 +52,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Use TLS but skip chain & host verification. # insecure_skip_verify = false - + ## If 'use_system_proxy' is set to true, Telegraf will check env vars such as ## HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or their lowercase counterparts). ## If 'use_system_proxy' is set to false (default) and 'http_proxy_url' is diff --git a/plugins/inputs/logstash/sample.conf b/plugins/inputs/logstash/sample.conf index 20506d4c8..48afffc37 100644 --- a/plugins/inputs/logstash/sample.conf +++ b/plugins/inputs/logstash/sample.conf @@ -25,7 +25,7 @@ ## Use TLS but skip chain & host verification. # insecure_skip_verify = false - + ## If 'use_system_proxy' is set to true, Telegraf will check env vars such as ## HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or their lowercase counterparts). ## If 'use_system_proxy' is set to false (default) and 'http_proxy_url' is diff --git a/plugins/inputs/lustre2/README.md b/plugins/inputs/lustre2/README.md index 301352b97..04b419bef 100644 --- a/plugins/inputs/lustre2/README.md +++ b/plugins/inputs/lustre2/README.md @@ -1,10 +1,18 @@ # Lustre Input Plugin -The [Lustre][]® file system is an open-source, parallel file system that -supports many requirements of leadership class HPC simulation environments. +This plugin gathers metrics for the [Lustre® file system][lustre] using its +entries in the `proc` filesystem. Reference the +[Lustre Monitoring and Statistics Guide][guide] for the reported information. -This plugin monitors the Lustre file system using its entries in the proc -filesystem. +> [!NOTE] This plugin doesn't report _all_ information available but only a +> limited set of items. Check the [metrics section](#metrics). + +⭐ Telegraf v0.1.5 +🏷️ system +💻 linux + +[lustre]: http://lustre.org/ +[guide]: http://wiki.lustre.org/Lustre_Monitoring_and_Statistics_Guide ## Global configuration options @@ -187,19 +195,9 @@ From `/proc/fs/lustre/*/*/eviction_count`: - fields: - evictions -## Troubleshooting - -Check for the default or custom procfiles in the proc filesystem, and reference -the [Lustre Monitoring and Statistics Guide][guide]. This plugin does not -report all information from these files, only a limited set of items -corresponding to the above metric fields. - ## Example Output ```text lustre2,host=oss2,jobid=42990218,name=wrk-OST0041 jobstats_ost_setattr=0i,jobstats_ost_sync=0i,jobstats_punch=0i,jobstats_read_bytes=4096i,jobstats_read_calls=1i,jobstats_read_max_size=4096i,jobstats_read_min_size=4096i,jobstats_write_bytes=310206488i,jobstats_write_calls=7423i,jobstats_write_max_size=53048i,jobstats_write_min_size=8820i 1556525847000000000 lustre2,host=mds1,jobid=42992017,name=wrk-MDT0000 jobstats_close=31798i,jobstats_crossdir_rename=0i,jobstats_getattr=34146i,jobstats_getxattr=15i,jobstats_link=0i,jobstats_mkdir=658i,jobstats_mknod=0i,jobstats_open=31797i,jobstats_rename=0i,jobstats_rmdir=0i,jobstats_samedir_rename=0i,jobstats_setattr=1788i,jobstats_setxattr=0i,jobstats_statfs=0i,jobstats_sync=0i,jobstats_unlink=0i 1556525828000000000 ``` - -[lustre]: http://lustre.org/ -[guide]: http://wiki.lustre.org/Lustre_Monitoring_and_Statistics_Guide diff --git a/plugins/inputs/lvm/README.md b/plugins/inputs/lvm/README.md index 358afb90c..15e44ec28 100644 --- a/plugins/inputs/lvm/README.md +++ b/plugins/inputs/lvm/README.md @@ -1,7 +1,14 @@ -# LVM Input Plugin +# Logical Volume Manager Input Plugin -The Logical Volume Management (LVM) input plugin collects information about -physical volumes, volume groups, and logical volumes. +This plugin collects information about physical volumes, volume groups and +logical volumes from the Logical Volume Management (LVM) of the +[Linux kernel][kernel]. + +⭐ Telegraf v1.21.0 +🏷️ system +💻 linux + +[kernel]: https://www.kernel.org/ ## Global configuration options diff --git a/plugins/inputs/mailchimp/README.md b/plugins/inputs/mailchimp/README.md index 0320cf874..dd7285585 100644 --- a/plugins/inputs/mailchimp/README.md +++ b/plugins/inputs/mailchimp/README.md @@ -1,8 +1,14 @@ # Mailchimp Input Plugin -Pulls campaign reports from the [Mailchimp API][1]. +This plugin gathers metrics from the [Mailchimp][mailchimp] service using the +[Mailchimp API][api]. -[1]: https://developer.mailchimp.com/ +⭐ Telegraf v0.2.4 +🏷️ cloud, web +💻 all + +[mailchimp]: https://mailchimp.com +[api]: https://developer.mailchimp.com/ ## Global configuration options @@ -68,3 +74,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. - list_stats_click_rate (double, percentage) ## Example Output + +```text +mailchimp,campaign_title=Freddie's\ Jokes\ Vol.\ 1,id=42694e9e57 abuse_reports=0i,click_rate=42,clicks_total=42i,emails_sent=200i,facebook_likes=42i,facebook_recipient_likes=5i,facebook_unique_likes=8i,forwards_count=0i,forwards_opens=0i,hard_bounces=0i,industry_abuse_rate=0.00021111996110887,industry_bounce_rate=0.0063767751251474,industry_click_rate=0.027431311866951,industry_open_rate=0.17076777144396,industry_type="Social Networks and Online Communities",industry_unopen_rate=0.82285545343089,industry_unsub_rate=0.001436957032815,list_stats_click_rate=42,list_stats_open_rate=42,list_stats_sub_rate=10,list_stats_unsub_rate=20,open_rate=42,opens_total=186i,soft_bounces=2i,syntax_errors=0i,unique_clicks=400i,unique_opens=100i,unique_subscriber_clicks=42i,unsubscribed=2i 1741188555526302348 +``` diff --git a/plugins/inputs/marklogic/README.md b/plugins/inputs/marklogic/README.md index e35d3f67b..5a60e4992 100644 --- a/plugins/inputs/marklogic/README.md +++ b/plugins/inputs/marklogic/README.md @@ -1,7 +1,13 @@ # MarkLogic Input Plugin -The MarkLogic Telegraf plugin gathers health status metrics from one or more -host. +This plugin gathers health status metrics from one or more [MarkLogic][marklogic] +hosts. + +⭐ Telegraf v1.12.0 +🏷️ server +💻 all + +[marklogic]: https://www.progress.com/marklogic ## Global configuration options diff --git a/plugins/inputs/mcrouter/README.md b/plugins/inputs/mcrouter/README.md index 6984217fe..6e7ed880c 100644 --- a/plugins/inputs/mcrouter/README.md +++ b/plugins/inputs/mcrouter/README.md @@ -1,6 +1,15 @@ # Mcrouter Input Plugin -This plugin gathers statistics data from a Mcrouter server. +This plugin gathers statistics data from [Mcrouter][mcrouter] instances, a +protocol router, developed and maintained by Facebook, for scaling +[memcached][memcached] deployments. + +⭐ Telegraf v1.7.0 +🏷️ applications, network +💻 all + +[mcrouter]: https://github.com/facebook/mcrouter +[memcached]: http://memcached.org/ ## Global configuration options @@ -28,8 +37,7 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. The fields from this plugin are gathered in the *mcrouter* measurement. -Description of gathered fields can be found -[here](https://github.com/facebook/mcrouter/wiki/Stats-list). +Description of gathered fields can be found in the [project wiki][wiki]. Fields: @@ -98,6 +106,8 @@ Fields: * cmd_delete_out_all * cmd_lease_set_out_all +[wiki]: https://github.com/facebook/mcrouter/wiki/Stats-list + ## Tags * Mcrouter measurements have the following tags: diff --git a/plugins/inputs/mdstat/README.md b/plugins/inputs/mdstat/README.md index 1824f352c..16b65737f 100644 --- a/plugins/inputs/mdstat/README.md +++ b/plugins/inputs/mdstat/README.md @@ -1,17 +1,17 @@ -# mdstat Input Plugin +# MD RAID Statistics Input Plugin -The mdstat plugin gathers statistics about any Linux MD RAID arrays configured -on the host by reading /proc/mdstat. For a full list of available fields see -the /proc/mdstat section of the [proc man page][man-proc]. For a better idea -of what each field represents, see the [mdstat man page][man-mdstat]. +This plugin gathers statistics about any [Linux MD RAID arrays][mdraid] +configured on the host by reading `/proc/mdstat`. For a full list of available +fields see the `/proc/mdstat` section of the [proc man page][man_proc]. For +details on the fields check the [mdstat wiki][mdstat_wiki]. -Stat collection based on Prometheus' [mdstat collection library][prom-lib]. +⭐ Telegraf v1.20.0 +🏷️ system +💻 linux -[man-proc]: http://man7.org/linux/man-pages/man5/proc.5.html - -[man-mdstat]: https://raid.wiki.kernel.org/index.php/Mdstat - -[prom-lib]: https://github.com/prometheus/procfs/blob/master/mdstat.go +[mdraid]: https://docs.kernel.org/admin-guide/md.html +[man_proc]: http://man7.org/linux/man-pages/man5/proc.5.html +[mdstat_wiki]: https://raid.wiki.kernel.org/index.php/Mdstat ## Global configuration options @@ -35,27 +35,25 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. ## Metrics -- mdstat - - BlocksSynced (if the array is rebuilding/checking, this is the count of - blocks that have been scanned) - - BlocksSyncedFinishTime (the expected finish time of the rebuild scan, - listed in minutes remaining) - - BlocksSyncedPct (the percentage of the rebuild scan left) - - BlocksSyncedSpeed (the current speed the rebuild is running at, listed - in K/sec) - - BlocksTotal (the total count of blocks in the array) - - DisksActive (the number of disks that are currently considered healthy - in the array) - - DisksFailed (the current count of failed disks in the array) - - DisksSpare (the current count of "spare" disks in the array) - - DisksTotal (total count of disks in the array) - -## Tags - -- mdstat - - ActivityState (`active` or `inactive`) - - Devices (comma separated list of devices that make up the array) - - Name (name of the array) +- `mdstat` metric + - tags: + - ActivityState (`active` or `inactive`) + - Devices (comma separated list of devices that make up the array) + - Name (name of the array) + - fields: + - BlocksSynced (if the array is rebuilding/checking, this is the count of + blocks that have been scanned) + - BlocksSyncedFinishTime (the expected finish time of the rebuild scan, + listed in minutes remaining) + - BlocksSyncedPct (the percentage of the rebuild scan left) + - BlocksSyncedSpeed (the current speed the rebuild is running at, listed + in K/sec) + - BlocksTotal (the total count of blocks in the array) + - DisksActive (the number of disks that are currently considered healthy + in the array) + - DisksFailed (the current count of failed disks in the array) + - DisksSpare (the current count of "spare" disks in the array) + - DisksTotal (total count of disks in the array) ## Example Output diff --git a/plugins/inputs/mem/README.md b/plugins/inputs/mem/README.md index ac528e918..aeb3f5657 100644 --- a/plugins/inputs/mem/README.md +++ b/plugins/inputs/mem/README.md @@ -1,9 +1,16 @@ # Memory Input Plugin -The mem plugin collects system memory metrics. +This plugin collects metrics about the system memory. -For a more complete explanation of the difference between *used* and -*actual_used* RAM, see [Linux ate my ram](http://www.linuxatemyram.com/). +> [!TIP] +> For an explanation of the difference between *used* and *actual_used* +> RAM, see [Linux ate my ram][linux_ate_my_ram]. + +⭐ Telegraf v0.1.5 +🏷️ system +💻 all + +[linux_ate_my_ram]: http://www.linuxatemyram.com/ ## Global configuration options diff --git a/plugins/inputs/memcached/README.md b/plugins/inputs/memcached/README.md index 4d30623d1..dfc17376e 100644 --- a/plugins/inputs/memcached/README.md +++ b/plugins/inputs/memcached/README.md @@ -1,6 +1,12 @@ # Memcached Input Plugin -This plugin gathers statistics data from a Memcached server. +This plugin gathers statistics data from [Memcached][memcached] instances. + +⭐ Telegraf v0.1.2 +🏷️ server +💻 all + +[memcached]: https://memcached.org/ ## Global configuration options diff --git a/plugins/inputs/mesos/README.md b/plugins/inputs/mesos/README.md index 98fa2e922..ebcb4482c 100644 --- a/plugins/inputs/mesos/README.md +++ b/plugins/inputs/mesos/README.md @@ -1,9 +1,14 @@ -# Mesos Input Plugin +# Apache Mesos Input Plugin -This input plugin gathers metrics from Mesos. For more information, please -check the [Mesos Observability Metrics][1] page. +This plugin gathers metrics from [Apache Mesos][mesos] instances. For more +information, please check the [Mesos Observability Metrics][monitoring] page. -[1]: http://mesos.apache.org/documentation/latest/monitoring/ +⭐ Telegraf v0.10.3 +🏷️ containers +💻 all + +[mesos]:https://mesos.apache.org/ +[monitoring]: http://mesos.apache.org/documentation/latest/monitoring/ ## Global configuration options diff --git a/plugins/inputs/minecraft/README.md b/plugins/inputs/minecraft/README.md index ada30d2d3..19ff28f47 100644 --- a/plugins/inputs/minecraft/README.md +++ b/plugins/inputs/minecraft/README.md @@ -1,46 +1,18 @@ # Minecraft Input Plugin -The `minecraft` plugin connects to a Minecraft server using the RCON protocol -to collects scores from the server [scoreboard][]. +This plugin collects score metrics from a [Minecraft][minecraft] server using +the RCON protocol. -This plugin is known to support Minecraft Java Edition versions 1.11 - 1.14. -When using an version of Minecraft earlier than 1.13, be aware that the values -for some criterion has changed and may need to be modified. +> [!NOTE] +> This plugin supports Minecraft Java Edition versions 1.11 - 1.14. When using +> a version earlier than 1.13, be aware that the values for some criteria has +> changed and need to be modified. -## Server Setup +⭐ Telegraf v1.4.0 +🏷️ server +💻 all -Enable [RCON][] on the Minecraft server, add this to your server configuration -in the [server.properties][] file: - -```conf -enable-rcon=true -rcon.password= -rcon.port=<1-65535> -``` - -Scoreboard [Objectives][] must be added using the server console for the -plugin to collect. These can be added in game by players with op status, -from the server console, or over an RCON connection. - -When getting started pick an easy to test objective. This command will add an -objective that counts the number of times a player has jumped: - -```sh -/scoreboard objectives add jumps minecraft.custom:minecraft.jump -``` - -Once a player has triggered the event they will be added to the scoreboard, -you can then list all players with recorded scores: - -```sh -/scoreboard players list -``` - -View the current scores with a command, substituting your player name: - -```sh -/scoreboard players list Etho -``` +[minecraft]: https://www.minecraft.net/ ## Global configuration options @@ -69,6 +41,45 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. # tagdrop = ["server"] ``` +### Server Setup + +Enable [RCON][rcon] on the Minecraft server and add the following to your +[`server.properties`][propfile] file: + +```conf +enable-rcon=true +rcon.password= +rcon.port=<1-65535> +``` + +Scoreboard [objectives][objectives] must be added using the server console for +the plugin to collect. These can be added in game by players with op status, +from the server console, or over an RCON connection. + +When getting started pick an easy to test objective. This command will add an +objective that counts the number of times a player has jumped: + +```sh +/scoreboard objectives add jumps minecraft.custom:minecraft.jump +``` + +Once a player has triggered the event they will be added to the scoreboard, +you can then list all players with recorded scores: + +```sh +/scoreboard players list +``` + +View the current scores with a command, substituting your player name: + +```sh +/scoreboard players list Etho +``` + +[rcon]: http://wiki.vg/RCON +[propfile]: https://minecraft.gamepedia.com/Server.properties +[objectives]: https://minecraft.gamepedia.com/Scoreboard#Objectives + ## Metrics - minecraft @@ -80,14 +91,6 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details. - fields: - `` (integer, count) -## Sample Queries - -Get the number of jumps per player in the last hour: - -```sql -SELECT SPREAD("jumps") FROM "minecraft" WHERE time > now() - 1h GROUP BY "player" -``` - ## Example Output ```text @@ -95,8 +98,3 @@ minecraft,player=notch,source=127.0.0.1,port=25575 jumps=178i 149826139700000000 minecraft,player=dinnerbone,source=127.0.0.1,port=25575 deaths=1i,jumps=1999i,cow_kills=1i 1498261397000000000 minecraft,player=jeb,source=127.0.0.1,port=25575 d_pickaxe=1i,damage_dealt=80i,d_sword=2i,hunger=20i,health=20i,kills=1i,level=33i,jumps=264i,armor=15i 1498261397000000000 ``` - -[server.properties]: https://minecraft.gamepedia.com/Server.properties -[scoreboard]: http://minecraft.gamepedia.com/Scoreboard -[objectives]: https://minecraft.gamepedia.com/Scoreboard#Objectives -[rcon]: http://wiki.vg/RCON diff --git a/plugins/inputs/mock/README.md b/plugins/inputs/mock/README.md index cc420cdca..8208efd4d 100644 --- a/plugins/inputs/mock/README.md +++ b/plugins/inputs/mock/README.md @@ -1,11 +1,13 @@ # Mock Data Input Plugin -The mock input plugin generates random data based on a selection of different -algorithms. For example, it can produce random data between a set of values, -fake stock data, sine waves, and step-wise values. +The plugin generates mock-metrics based on different algorithms like sine-wave +functions, random numbers and more with the configured names and tags. Those +metrics are usefull during testing (e.g. processors) or if random data is +required. -Additionally, users can set the measurement name and tags used to whatever is -required to mock their situation. +⭐ Telegraf v1.22.0 +🏷️ testing +💻 all ## Global configuration options @@ -61,12 +63,12 @@ The mock plugin only requires that: The available algorithms for generating mock data include: -* Constant - generate a field with the given value of type string, float, int +* `constant`: generate a field with the given value of type string, float, int or bool -* Random Float - generate a random float, inclusive of min and max -* Sine Wave - produce a sine wave with a certain amplitude, period and baseline -* Step - always add the step value, negative values accepted -* Stock - generate fake, stock-like price values based on a volatility variable +* `random`: generate a random float, inclusive of min and max +* `sine_wave`: produce a sine wave with a certain amplitude, period and baseline +* `step`: always add the step value, negative values accepted +* `stock`: generate fake, stock-like price values based on a volatility variable ## Metrics diff --git a/plugins/inputs/modbus/README.md b/plugins/inputs/modbus/README.md index bc6be1452..6ba263b7e 100644 --- a/plugins/inputs/modbus/README.md +++ b/plugins/inputs/modbus/README.md @@ -1,8 +1,14 @@ # Modbus Input Plugin -The Modbus plugin collects Discrete Inputs, Coils, Input Registers and Holding -Registers via Modbus TCP or Modbus RTU/ASCII. +This plugin collects data from [Modbus][modbus] registers using e.g. Modbus TCP +or serial interfaces with Modbus RTU or Modbus ASCII. + +⭐ Telegraf v1.14.0 +🏷️ iot +💻 all + +[modbus]: https://www.modbus.org/ ## Global configuration options @@ -411,7 +417,7 @@ This is the original style used by this plugin. It allows a per-register configuration for a single slave-device. > [!NOTE] -> _For legacy reasons this configuration style is not completely consistent with the other styles. +> For legacy reasons this configuration style is not completely consistent with the other styles. #### Usage of `data_type` @@ -814,11 +820,6 @@ __Please note:__ These tags take precedence over predefined tags such as `name`, --- -## Metrics - -Metrics are custom and configured using the `discrete_inputs`, `coils`, -`holding_register` and `input_registers` options. - ## Troubleshooting ### Strange data @@ -872,8 +873,13 @@ are required for your device, please let us know. In case your device needs a workaround that is not yet implemented, please open an issue or submit a pull-request. +## Metrics + +The plugin reads the configured registers and constructs metrics based on the +specified configuration. There is no predefined metric format. + ## Example Output ```text -modbus.InputRegisters,host=orangepizero Current=0,Energy=0,Frequency=60,Power=0,PowerFactor=0,Voltage=123.9000015258789 1554079521000000000 +modbus,name=device,slave_id=1,type=holding_register energy=3254.5,power=23.5,frequency=49,97 1701777274026591864 ``` diff --git a/plugins/inputs/mongodb/README.md b/plugins/inputs/mongodb/README.md index 37e5276fb..fbdedf9ea 100644 --- a/plugins/inputs/mongodb/README.md +++ b/plugins/inputs/mongodb/README.md @@ -1,8 +1,17 @@ # MongoDB Input Plugin -See the [MongoDB Software Lifecycle Schedules][lifecycles] for supported -versions. +This plugin collects metrics about [MongoDB][mongodb] server instances by +running database commands. +> [!NOTE] +> This plugin supports all versions marked as supported in the +> [MongoDB Software Lifecycle Schedules][lifecycles]. + +⭐ Telegraf v0.1.5 +🏷️ datastore +💻 all + +[mongodb]: https://www.mongodb.com [lifecycles]: https://www.mongodb.com/support-policy/lifecycles ## Global configuration options diff --git a/plugins/inputs/monit/README.md b/plugins/inputs/monit/README.md index dcaeb4e46..14fdfcd18 100644 --- a/plugins/inputs/monit/README.md +++ b/plugins/inputs/monit/README.md @@ -1,13 +1,16 @@ # Monit Input Plugin -The `monit` plugin gathers metrics and status information about local processes, -remote hosts, file, file systems, directories and network interfaces managed +This plugin gathers metrics and status information about local processes, +remote hosts, files, file systems, directories and network interfaces managed and watched over by [Monit][monit]. -The use this plugin you should first enable the [HTTPD TCP port][httpd] in -Monit. +> [!NOTE] +> The plugin supports Monit version 5.16+. +> To use this plugin you have to enable the [HTTPD TCP port][httpd] in Monit. -Minimum Version of Monit tested with is 5.16. +⭐ Telegraf v1.14.0 +🏷️ network +💻 all [monit]: https://mmonit.com/ [httpd]: https://mmonit.com/monit/documentation/monit.html#TCP-PORT diff --git a/plugins/inputs/mqtt_consumer/README.md b/plugins/inputs/mqtt_consumer/README.md index 6b8065d39..e66e5cc43 100644 --- a/plugins/inputs/mqtt_consumer/README.md +++ b/plugins/inputs/mqtt_consumer/README.md @@ -1,7 +1,14 @@ # MQTT Consumer Input Plugin -The [MQTT][mqtt] consumer plugin reads from the specified MQTT topics -and creates metrics using one of the supported [input data formats][]. +This service plugin consumes messages from [MQTT][mqtt] brokers for the +configured topics in one of the supported [data formats][data_formats]. + +⭐ Telegraf v0.10.3 +🏷️ messaging +💻 all + +[mqtt]: https://mqtt.org +[data_formats]: /docs/DATA_FORMATS_INPUT.md ## Service Input @@ -264,6 +271,3 @@ This will result in the following metric: ```text internal_mqtt_consumer host=pop-os version=1.24.0 messages_received=622i payload_size=37942i 1657282270000000000 ``` - -[mqtt]: https://mqtt.org -[input data formats]: /docs/DATA_FORMATS_INPUT.md diff --git a/plugins/inputs/multifile/README.md b/plugins/inputs/multifile/README.md index 2c37b2305..b811351ce 100644 --- a/plugins/inputs/multifile/README.md +++ b/plugins/inputs/multifile/README.md @@ -1,12 +1,18 @@ # Multifile Input Plugin -The multifile input plugin allows Telegraf to combine data from multiple files -into a single metric, creating one field or tag per file. This is often -useful creating custom metrics from the `/sys` or `/proc` filesystems. +This plugin reads the combined data from multiple files into a single metric, +creating one field or tag per file. This is often useful creating custom +metrics from the `/sys` or `/proc` filesystems. -> Note: If you wish to parse metrics from a single file formatted in one of -> the supported [input data formats][], you should use the [file][] input -> plugin instead. +> [!NOTE] +> To parse metrics from a single file you should use the [file][file_plugin] +> input plugin instead. + +⭐ Telegraf v1.10.0 +🏷️ system +💻 all + +[file_plugin]: /plugins/inputs/file/README.md ## Global configuration options @@ -88,6 +94,3 @@ The kernel driver provides the following files in * `in_humidityrelative_input`: `48900` * `in_pressure_input`: `101.343285156` * `in_temp_input`: `20400` - -[input data formats]: /docs/DATA_FORMATS_INPUT.md -[file]: /plugins/inputs/file/README.md diff --git a/plugins/inputs/mysql/README.md b/plugins/inputs/mysql/README.md index 22aa69271..0d6594b85 100644 --- a/plugins/inputs/mysql/README.md +++ b/plugins/inputs/mysql/README.md @@ -1,26 +1,16 @@ # MySQL Input Plugin -This plugin gathers the statistic data from MySQL server +This plugin gathers statistics from [MySQL][mysql] server instances. -* Global statuses -* Global variables -* Slave statuses -* Binlog size -* Process list -* User Statistics -* Info schema auto increment columns -* InnoDB metrics -* Table I/O waits -* Index I/O waits -* Perf Schema table lock waits -* Perf Schema event waits -* Perf Schema events statements -* File events statistics -* Table schema statistics +> [!NOTE] +> To gather metrics from the performance schema, it must first be enabled in +> MySQL. See the performance schema [quick start][quick-start] for details. -In order to gather metrics from the performance schema, it must first be enabled -in mySQL configuration. See the performance schema [quick start][quick-start]. +⭐ Telegraf v0.1.1 +🏷️ datastore +💻 all +[mysql]: https://www.mysql.com/ [quick-start]: https://dev.mysql.com/doc/refman/8.0/en/performance-schema-quick-start.html ## Global configuration options