docs: Explain and note service inputs (#12870)

docs/includes/service_input.md

@@ -0,0 +1,8 @@
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin

plugins/inputs/amqp_consumer/README.md

@@ -14,6 +14,17 @@ For an introduction to AMQP see:
 - [amqp - concepts](https://www.rabbitmq.com/tutorials/amqp-concepts.html)
 - [rabbitmq: getting started](https://www.rabbitmq.com/getstarted.html)
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/cisco_telemetry_mdt/README.md

@@ -12,6 +12,17 @@ later, IOS XE 16.10 and later, as well as NX-OS 7.x and later platforms.
 The TCP dialout transport is supported on IOS XR (32-bit and 64-bit) 6.1.x and
 later.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/cloud_pubsub/README.md

@@ -3,6 +3,17 @@
 The GCP PubSub plugin ingests metrics from [Google Cloud PubSub][pubsub]
 and creates metrics using one of the supported [input data formats][].
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/cloud_pubsub_push/README.md

@@ -14,6 +14,17 @@ Enable mutually authenticated TLS and authorize client connections by signing
 certificate authority by including a list of allowed CA certificate file names
 in `tls_allowed_cacerts`.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/cloudwatch_metric_streams/README.md

@@ -7,6 +7,17 @@ for metrics sent via HTTP and performs the required processing for
 For cost, see the Metric Streams example in
 [CloudWatch pricing](#troubleshooting-documentation).
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/eventhub_consumer/README.md

@@ -13,6 +13,17 @@ The main focus for development of this plugin is Azure IoT hub:
 3. The connection string needed for the plugin is located under *Shared access
    policies*, both the *iothubowner* and *service* policies should work
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/execd/README.md

@@ -13,6 +13,17 @@ new line to the process's STDIN.
 
 STDERR from the process will be relayed to Telegraf as errors in the logs.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/gnmi/README.md

@@ -11,6 +11,17 @@ It has been optimized to support gNMI telemetry as produced by Cisco IOS XR
 
 [1]: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-specification.md
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/http_listener_v2/README.md

@@ -11,6 +11,17 @@ metrics in [InfluxDB Line Protocol][line_protocol] it's recommended to use the
 InfluxDB it is recommended to use [`influxdb_listener`][influxdb_listener] or
 [`influxdb_v2_listener`][influxdb_v2_listener].
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/influxdb_listener/README.md

@@ -18,6 +18,17 @@ receive a 200 OK response with message body `{"results":[]}` but they are not
 relayed. The output configuration of the Telegraf instance which ultimately
 submits data to InfluxDB determines the destination database.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/influxdb_v2_listener/README.md

@@ -11,6 +11,17 @@ to the output plugins configuration.
 
 Telegraf minimum version: Telegraf 1.16.0
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/intel_rdt/README.md

@@ -91,6 +91,17 @@ process availability.
 - Enabling OS interface: <https://github.com/intel/intel-cmt-cat/wiki>, <https://github.com/intel/intel-cmt-cat/wiki/resctrl>
 - More about Intel RDT: <https://www.intel.com/content/www/us/en/architecture-and-technology/resource-director-technology.html>
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/jti_openconfig_telemetry/README.md

@@ -7,6 +7,17 @@ from listed sensors using Junos Telemetry Interface. Refer to
 
 [1]: https://www.juniper.net/documentation/en_US/junos/topics/concept/junos-telemetry-interface-oveview.html
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/kafka_consumer/README.md

@@ -6,6 +6,17 @@ and creates metrics using one of the supported [input data formats][].
 For old kafka version (< 0.8), please use the [kafka_consumer_legacy][] input
 plugin and use the old zookeeper connection method.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/kafka_consumer_legacy/README.md

@@ -9,6 +9,17 @@ instances of telegraf can read from the same topic in parallel.
 
 [1]: http://godoc.org/github.com/wvanbergen/kafka/consumergroup
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/kinesis_consumer/README.md

@@ -3,6 +3,17 @@
 The [Kinesis][kinesis] consumer plugin reads from a Kinesis data stream
 and creates metrics using one of the supported [input data formats][].
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/knx_listener/README.md

@@ -5,6 +5,17 @@ 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 (<https://github.com/vapourismo/knx-go>).
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/lanz/README.md

@@ -13,6 +13,17 @@ This plugin uses Arista's sdk.
 
 - <https://github.com/aristanetworks/goarista>
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/logparser/README.md

@@ -46,6 +46,17 @@ Migration Example:
 +   data_format = "grok"
 ```
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/mqtt_consumer/README.md

@@ -3,6 +3,17 @@
 The [MQTT][mqtt] consumer plugin reads from the specified MQTT topics
 and creates metrics using one of the supported [input data formats][].
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/nats_consumer/README.md

@@ -6,6 +6,17 @@ creates metrics using one of the supported [input data formats][].
 A [Queue Group][queue group] is used when subscribing to subjects so multiple
 instances of telegraf can read from a NATS cluster in parallel.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/netflow/README.md

@@ -15,6 +15,17 @@ Definitions for IPFIX are according to [IANA assignement document][IPFIX doc].
 [ASA extensions]:   https://www.cisco.com/c/en/us/td/docs/security/asa/special/netflow/asa_netflow.html
 [IPFIX doc]:        https://www.iana.org/assignments/ipfix/ipfix.xhtml#ipfix-nat-type
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/nsq_consumer/README.md

@@ -3,6 +3,17 @@
 The [NSQ][nsq] consumer plugin reads from NSQD and creates metrics using one
 of the supported [input data formats][].
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/opcua_listener/README.md

@@ -5,6 +5,17 @@ The `opcua_listener` plugin subscribes to data from OPC UA Server devices.
 Telegraf minimum version: Telegraf 1.25
 Plugin minimum tested version: 1.25
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/opentelemetry/README.md

@@ -3,6 +3,17 @@
 This plugin receives traces, metrics and logs from
 [OpenTelemetry](https://opentelemetry.io) clients and agents via gRPC.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/riemann_listener/README.md

@@ -3,6 +3,17 @@
 The Riemann Listener is a simple input plugin that listens for messages from
 client that use riemann clients using riemann-protobuff format.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/sflow/README.md

@@ -18,6 +18,17 @@ avoid cardinality issues:
 - Monitor your databases [series cardinality][].
 - Consult the [InfluxDB documentation][influx-docs] for the most up-to-date techniques.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/socket_listener/README.md

@@ -6,6 +6,17 @@ streaming (tcp, unix) or datagram (udp, unixgram) protocols.
 The plugin expects messages in the [Telegraf Input Data
 Formats](../../../docs/DATA_FORMATS_INPUT.md).
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/statsd/README.md

@@ -2,6 +2,17 @@
 
 The StatsD input plugin gathers metrics from a Statsd server.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/suricata/README.md

@@ -6,6 +6,17 @@ and much more. It provides a socket for the Suricata log output to write JSON
 stats output to, and processes the incoming data to fit Telegraf's format.
 It can also report for triggered Suricata IDS/IPS alerts.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/syslog/README.md

@@ -10,6 +10,17 @@ Syslog messages should be formatted according to
 [RFC 5424](https://tools.ietf.org/html/rfc5424) (syslog protocol) or
 [RFC 3164](https://tools.ietf.org/html/rfc3164) (BSD syslog protocol).
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/tail/README.md

@@ -19,6 +19,17 @@ see <http://man7.org/linux/man-pages/man1/tail.1.html> for more details.
 The plugin expects messages in one of the [Telegraf Input Data
 Formats](../../../docs/DATA_FORMATS_INPUT.md).
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/tcp_listener/README.md

@@ -3,6 +3,17 @@
 **DEPRECATED: As of version 1.3 the TCP listener plugin has been deprecated in
 favor of the [socket_listener plugin](../socket_listener/README.md)**
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/udp_listener/README.md

@@ -3,6 +3,17 @@
 **DEPRECATED: As of version 1.3 the UDP listener plugin has been deprecated in
 favor of the [socket_listener plugin](../socket_listener/README.md)**
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/webhooks/README.md

@@ -15,6 +15,17 @@ cp config.conf.new /etc/telegraf/telegraf.conf
 sudo service telegraf start
 ```
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support

plugins/inputs/win_eventlog/README.md

@@ -26,8 +26,8 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
 # Input plugin to collect Windows Event Log messages
 # This plugin ONLY supports Windows
 [[inputs.win_eventlog]]
-  ## Telegraf should have Administrator permissions to subscribe for some Windows Events channels
+  ## Telegraf should have Administrator permissions to subscribe for some
-  ## (System log, for example)
+  ## Windows Events channels (e.g. System log)
 
   ## LCID (Locale ID) for event rendering
   ## 1033 to force English language
@@ -65,46 +65,58 @@ See the [CONFIGURATION.md][CONFIGURATION.md] for more details.
   </QueryList>
   '''
 
-  ## When true, event logs are read from the beginning; otherwise only future events
+  ## When true, event logs are read from the beginning; otherwise only future
-  ## will be logged.
+  ## events will be logged.
   # from_beginning = false
 
-  ## System field names:
-  ##   "Source", "EventID", "Version", "Level", "Task", "Opcode", "Keywords", "TimeCreated",
-  ##   "EventRecordID", "ActivityID", "RelatedActivityID", "ProcessID", "ThreadID", "ProcessName",
-  ##   "Channel", "Computer", "UserID", "UserName", "Message", "LevelText", "TaskText", "OpcodeText"
-
-  ## In addition to System, Data fields can be unrolled from additional XML nodes in event.
-  ## Human-readable representation of those nodes is formatted into event Message field,
-  ## but XML is more machine-parsable
-
   # Process UserData XML to fields, if this node exists in Event XML
-  process_userdata = true
+  # process_userdata = true
 
   # Process EventData XML to fields, if this node exists in Event XML
-  process_eventdata = true
+  # process_eventdata = true
 
   ## Separator character to use for unrolled XML Data field names
-  separator = "_"
+  # separator = "_"
 
-  ## Get only first line of Message field. For most events first line is usually more than enough
+  ## Get only first line of Message field. For most events first line is
-  only_first_line_of_message = true
+  ## usually more than enough
+  # only_first_line_of_message = true
 
   ## Parse timestamp from TimeCreated.SystemTime event field.
-  ## Will default to current time of telegraf processing on parsing error or if set to false
+  ## Will default to current time of telegraf processing on parsing error or if
-  timestamp_from_event = true
+  ## set to false
+  # timestamp_from_event = true
 
-  ## Fields to include as tags. Globbing supported ("Level*" for both "Level" and "LevelText")
+  ## System field names:
-  event_tags = ["Source", "EventID", "Level", "LevelText", "Task", "TaskText", "Opcode", "OpcodeText", "Keywords", "Channel", "Computer"]
+  ##   "Source", "EventID", "Version", "Level", "Task", "Opcode", "Keywords",
+  ##   "TimeCreated", "EventRecordID", "ActivityID", "RelatedActivityID",
+  ##   "ProcessID", "ThreadID", "ProcessName", "Channel", "Computer", "UserID",
+  ##   "UserName", "Message", "LevelText", "TaskText", "OpcodeText"
+  ##
+  ## In addition to System, Data fields can be unrolled from additional XML
+  ## nodes in event. Human-readable representation of those nodes is formatted
+  ## into event Message field, but XML is more machine-parsable
 
-  ## Default list of fields to send. All fields are sent by default. Globbing supported
+  ## Event fields to include as tags
-  event_fields = ["*"]
+  ## The values below are included by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # event_tags = ["Source", "EventID", "Level", "LevelText", "Task", "TaskText", "Opcode", "OpcodeText", "Keywords", "Channel", "Computer"]
 
-  ## Fields to exclude. Also applied to data fields. Globbing supported
+  ## Event fields to include
-  exclude_fields = ["TimeCreated", "Binary", "Data_Address*"]
+  ## All fields are sent by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # event_fields = ["*"]
 
-  ## Skip those tags or fields if their value is empty or equals to zero. Globbing supported
+  ## Event fields to exclude
-  exclude_empty = ["*ActivityID", "UserID"]
+  ## Note that if you exclude all fields then no metrics are produced. A valid
+  ## metric includes at least one field.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # exclude_fields = []
+
+  ## Event fields to exclude if their value is empty or equals to zero
+  ## The values below are included by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # exclude_empty = ["Task", "Opcode", "*ActivityID", "UserID"]
 ```
 
 ### Filtering

plugins/inputs/win_eventlog/sample.conf

@@ -1,8 +1,8 @@
 # Input plugin to collect Windows Event Log messages
 # This plugin ONLY supports Windows
 [[inputs.win_eventlog]]
-  ## Telegraf should have Administrator permissions to subscribe for some Windows Events channels
+  ## Telegraf should have Administrator permissions to subscribe for some
-  ## (System log, for example)
+  ## Windows Events channels (e.g. System log)
 
   ## LCID (Locale ID) for event rendering
   ## 1033 to force English language
@@ -40,43 +40,55 @@
   </QueryList>
   '''
 
-  ## When true, event logs are read from the beginning; otherwise only future events
+  ## When true, event logs are read from the beginning; otherwise only future
-  ## will be logged.
+  ## events will be logged.
   # from_beginning = false
 
-  ## System field names:
-  ##   "Source", "EventID", "Version", "Level", "Task", "Opcode", "Keywords", "TimeCreated",
-  ##   "EventRecordID", "ActivityID", "RelatedActivityID", "ProcessID", "ThreadID", "ProcessName",
-  ##   "Channel", "Computer", "UserID", "UserName", "Message", "LevelText", "TaskText", "OpcodeText"
-
-  ## In addition to System, Data fields can be unrolled from additional XML nodes in event.
-  ## Human-readable representation of those nodes is formatted into event Message field,
-  ## but XML is more machine-parsable
-
   # Process UserData XML to fields, if this node exists in Event XML
-  process_userdata = true
+  # process_userdata = true
 
   # Process EventData XML to fields, if this node exists in Event XML
-  process_eventdata = true
+  # process_eventdata = true
 
   ## Separator character to use for unrolled XML Data field names
-  separator = "_"
+  # separator = "_"
 
-  ## Get only first line of Message field. For most events first line is usually more than enough
+  ## Get only first line of Message field. For most events first line is
-  only_first_line_of_message = true
+  ## usually more than enough
+  # only_first_line_of_message = true
 
   ## Parse timestamp from TimeCreated.SystemTime event field.
-  ## Will default to current time of telegraf processing on parsing error or if set to false
+  ## Will default to current time of telegraf processing on parsing error or if
-  timestamp_from_event = true
+  ## set to false
+  # timestamp_from_event = true
 
-  ## Fields to include as tags. Globbing supported ("Level*" for both "Level" and "LevelText")
+  ## System field names:
-  event_tags = ["Source", "EventID", "Level", "LevelText", "Task", "TaskText", "Opcode", "OpcodeText", "Keywords", "Channel", "Computer"]
+  ##   "Source", "EventID", "Version", "Level", "Task", "Opcode", "Keywords",
+  ##   "TimeCreated", "EventRecordID", "ActivityID", "RelatedActivityID",
+  ##   "ProcessID", "ThreadID", "ProcessName", "Channel", "Computer", "UserID",
+  ##   "UserName", "Message", "LevelText", "TaskText", "OpcodeText"
+  ##
+  ## In addition to System, Data fields can be unrolled from additional XML
+  ## nodes in event. Human-readable representation of those nodes is formatted
+  ## into event Message field, but XML is more machine-parsable
 
-  ## Default list of fields to send. All fields are sent by default. Globbing supported
+  ## Event fields to include as tags
-  event_fields = ["*"]
+  ## The values below are included by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # event_tags = ["Source", "EventID", "Level", "LevelText", "Task", "TaskText", "Opcode", "OpcodeText", "Keywords", "Channel", "Computer"]
 
-  ## Fields to exclude. Also applied to data fields. Globbing supported
+  ## Event fields to include
-  exclude_fields = ["TimeCreated", "Binary", "Data_Address*"]
+  ## All fields are sent by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # event_fields = ["*"]
 
-  ## Skip those tags or fields if their value is empty or equals to zero. Globbing supported
+  ## Event fields to exclude
-  exclude_empty = ["*ActivityID", "UserID"]
+  ## Note that if you exclude all fields then no metrics are produced. A valid
+  ## metric includes at least one field.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # exclude_fields = []
+
+  ## Event fields to exclude if their value is empty or equals to zero
+  ## The values below are included by default.
+  ## Globbing supported (e.g. "Level*" matches both "Level" and "LevelText")
+  # exclude_empty = ["Task", "Opcode", "*ActivityID", "UserID"]

plugins/inputs/zipkin/README.md

@@ -7,6 +7,17 @@ __Please Note:__ This plugin is experimental; Its data schema may be subject to
 change based on its main usage cases and the evolution of the OpenTracing
 standard.
 
+## Service Input <!-- @/docs/includes/service_input.md -->
+
+This plugin is a service input. Normal plugins gather metrics determined by the
+interval setting. Service plugins start a service to listens and waits for
+metrics or events to occur. Service plugins have two key differences from
+normal plugins:
+
+1. The global or plugin specific `interval` setting may not apply
+2. The CLI options of `--test`, `--test-wait`, and `--once` may not produce
+   output for this plugin
+
 ## Global configuration options <!-- @/docs/includes/plugin_config.md -->
 
 In addition to the plugin-specific configuration settings, plugins support