Rename http_listener to influxdb_listener

CHANGELOG.md

@@ -1,5 +1,17 @@
 ## v1.9 [unreleased]
 
+### Release Notes
+
+- The `http_listener` input plugin has been renamed to `influxdb_listener` and
+  use of the original name is deprecated.  The new name better describes the
+  intended use of the plugin as a InfluxDB relay.  For general purpose
+  transfer of metrics in any format via HTTP, it is recommended to use
+  `http_listener_v2` instead.
+
+### New Inputs
+
+- [http_listener_v2](/plugins/inputs/http_listener_v2/README.md) - Contributed by @jul1u5
+
 ### Features
 
 - [#4686](https://github.com/influxdata/telegraf/pull/4686): Add replace function to strings processor.

README.md

@@ -165,12 +165,14 @@ For documentation on the latest development code see the [documentation index][d
 * [haproxy](./plugins/inputs/haproxy)
 * [hddtemp](./plugins/inputs/hddtemp)
 * [httpjson](./plugins/inputs/httpjson) (generic JSON-emitting http service plugin)
-* [http_listener](./plugins/inputs/http_listener)
+* [http_listener](./plugins/inputs/influxdb_listener) (deprecated, renamed to [influxdb_listener](/plugins/inputs/influxdb_listener))
+* [http_listener_v2](./plugins/inputs/http_listener_v2)
 * [http](./plugins/inputs/http) (generic HTTP plugin, supports using input data formats)
 * [http_response](./plugins/inputs/http_response)
 * [icinga2](./plugins/inputs/icinga2)
 * [influxdb](./plugins/inputs/influxdb)
 * [influxdb_v2](./plugins/inputs/influxdb_v2)
+* [influxdb_listener](./plugins/inputs/influxdb_listener)
 * [internal](./plugins/inputs/internal)
 * [interrupts](./plugins/inputs/interrupts)
 * [ipmi_sensor](./plugins/inputs/ipmi_sensor)

plugins/inputs/all/all.go

@@ -40,12 +40,12 @@ import (
 	_ "github.com/influxdata/telegraf/plugins/inputs/haproxy"
 	_ "github.com/influxdata/telegraf/plugins/inputs/hddtemp"
 	_ "github.com/influxdata/telegraf/plugins/inputs/http"
-	_ "github.com/influxdata/telegraf/plugins/inputs/http_listener"
 	_ "github.com/influxdata/telegraf/plugins/inputs/http_listener_v2"
 	_ "github.com/influxdata/telegraf/plugins/inputs/http_response"
 	_ "github.com/influxdata/telegraf/plugins/inputs/httpjson"
 	_ "github.com/influxdata/telegraf/plugins/inputs/icinga2"
 	_ "github.com/influxdata/telegraf/plugins/inputs/influxdb"
+	_ "github.com/influxdata/telegraf/plugins/inputs/influxdb_listener"
 	_ "github.com/influxdata/telegraf/plugins/inputs/internal"
 	_ "github.com/influxdata/telegraf/plugins/inputs/interrupts"
 	_ "github.com/influxdata/telegraf/plugins/inputs/ipmi_sensor"

plugins/inputs/http_listener/README.md

@@ -1,48 +0,0 @@
-# HTTP listener service input plugin
-
-The HTTP listener is a service input plugin that listens for messages sent via HTTP POST.
-The plugin expects messages in the InfluxDB line-protocol ONLY, other Telegraf input data formats are not supported.
-The intent of the plugin is to allow Telegraf to serve as a proxy/router for the `/write` endpoint of the InfluxDB HTTP API.
-
-The `/write` endpoint supports the `precision` query parameter and can be set to one of `ns`, `u`, `ms`, `s`, `m`, `h`.  All other parameters are ignored and defer to the output plugins configuration.
-
-When chaining Telegraf instances using this plugin, CREATE DATABASE requests receive a 200 OK response with message body `{"results":[]}` but they are not relayed. The output configuration of the Telegraf instance which ultimately submits data to InfluxDB determines the destination database.
-
-Enable TLS by specifying the file names of a service TLS certificate and key.
-
-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````.
-
-Enable basic HTTP authentication of clients by specifying a username and password to check for. These credentials will be received from the client _as plain text_ if TLS is not configured.
-
-See: [Telegraf Input Data Formats](https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md#influx).
-
-**Example:**
-```
-curl -i -XPOST 'http://localhost:8186/write' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
-```
-
-### Configuration:
-
-This is a sample configuration for the plugin.
-
-```toml
-# # Influx HTTP write listener
-[[inputs.http_listener]]
-  ## Address and port to host HTTP listener on
-  service_address = ":8186"
-
-  ## timeouts
-  read_timeout = "10s"
-  write_timeout = "10s"
-
-  ## HTTPS
-  tls_cert= "/etc/telegraf/cert.pem"
-  tls_key = "/etc/telegraf/key.pem"
-
-  ## MTLS
-  tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
-
-  ## Basic authentication
-  basic_username = "foobar"
-  basic_password = "barfoo"
-```

plugins/inputs/http_listener_v2/README.md

@@ -1,21 +1,11 @@
-# Generic HTTP listener service input plugin
+# HTTP Listener v2 Input Plugin
 
-> NOTE: This is a new version of HTTP listener plugin.
-> This plugin supports all [data formats](/docs/DATA_FORMATS_INPUT.md) while the old [http_listener](/plugins/inputs/http_listener)
-> only accepts data in InfluxDB line-protocol only
+HTTP Listener v2 is a service input plugin that listens for metrics sent via
+HTTP.  Metrics may be sent in any supported [data format][data_format].
 
-The HTTP listener is a service input plugin that listens for messages sent via HTTP POST.
-
-Enable TLS by specifying the file names of a service TLS certificate and key.
-
-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````.
-
-Enable basic HTTP authentication of clients by specifying a username and password to check for. These credentials will be received from the client _as plain text_ if TLS is not configured.
-
-**Example:**
-```
-curl -i -XPOST 'http://localhost:8080/write' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
-```
+**Note:** The plugin previously known as `http_listener` has been renamed
+`influxdb_listener`.  If you would like Telegraf to act as a proxy/relay for
+InfluxDB it is recommended to use [`influxdb_listener`][influxdb_listener].
 
 ### Configuration:
 
@@ -41,7 +31,7 @@ This is a sample configuration for the plugin.
   ## 0 means to use the default of 536,870,912 bytes (500 mebibytes)
   max_body_size = 0
 
-  ## Set one or more allowed client CA certificate file names to 
+  ## Set one or more allowed client CA certificate file names to
   ## enable mutually authenticated TLS connections
   tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
 
@@ -60,3 +50,22 @@ This is a sample configuration for the plugin.
   ## https://github.com/influxdata/telegraf/blob/master/docs/DATA_FORMATS_INPUT.md
   data_format = "influx"
 ```
+
+### Metrics:
+
+Metrics are created from the request body and are dependant on the value of `data_format`.
+
+### Troubleshooting:
+
+**Send Line Protocol**
+```
+curl -i -XPOST 'http://localhost:8080/telegraf' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
+```
+
+**Send JSON**
+```
+curl -i -XPOST 'http://localhost:8080/telegraf' --data-binary '{"value1": 42, "value2": 42}'
+```
+
+[data_format]: /docs/DATA_FORMATS_INPUT.md
+[influxdb_listener]: /plugins/inputs/influxdb_listener/README.md

plugins/inputs/influxdb_listener/README.md

@@ -0,0 +1,67 @@
+# InfluxDB Listener Input Plugin
+
+InfluxDB Listener is a service input plugin that listens for requests sent
+according to the [InfluxDB HTTP API][influxdb_http_api].  The intent of the
+plugin is to allow Telegraf to serve as a proxy/router for the `/write`
+endpoint of the InfluxDB HTTP API.
+
+**Note:** This plugin was previously known as `http_listener`.  If you wish to
+send general metrics via HTTP it is recommended to use the
+[`http_listener_v2`][http_listener_v2] instead.
+
+The `/write` endpoint supports the `precision` query parameter and can be set
+to one of `ns`, `u`, `ms`, `s`, `m`, `h`.  All other parameters are ignored and
+defer to the output plugins configuration.
+
+When chaining Telegraf instances using this plugin, CREATE DATABASE requests
+receive a 200 OK response with message body `{"results":[]}` but they are not
+relayed. The output configuration of the Telegraf instance which ultimately
+submits data to InfluxDB determines the destination database.
+
+### Configuration:
+
+```toml
+[[inputs.influxdb_listener]]
+  ## Address and port to host HTTP listener on
+  service_address = ":8186"
+
+  ## maximum duration before timing out read of the request
+  read_timeout = "10s"
+  ## maximum duration before timing out write of the response
+  write_timeout = "10s"
+
+  ## Maximum allowed http request body size in bytes.
+  ## 0 means to use the default of 536,870,912 bytes (500 mebibytes)
+  max_body_size = 0
+
+  ## Maximum line size allowed to be sent in bytes.
+  ## 0 means to use the default of 65536 bytes (64 kibibytes)
+  max_line_size = 0
+
+  ## Set one or more allowed client CA certificate file names to
+  ## enable mutually authenticated TLS connections
+  tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
+
+  ## Add service certificate and key
+  tls_cert = "/etc/telegraf/cert.pem"
+  tls_key = "/etc/telegraf/key.pem"
+
+  ## Optional username and password to accept for HTTP basic authentication.
+  ## You probably want to make sure you have TLS configured above for this.
+  # basic_username = "foobar"
+  # basic_password = "barfoo"
+```
+
+### Metrics:
+
+Metrics are created from InfluxDB Line Protocol in the request body.
+
+### Troubleshooting:
+
+**Example Query:**
+```
+curl -i -XPOST 'http://localhost:8186/write' --data-binary 'cpu_load_short,host=server01,region=us-west value=0.64 1434055562000000000'
+```
+
+[influxdb_http_api]: https://docs.influxdata.com/influxdb/latest/guides/writing_data/
+[http_listener_v2]: /plugins/inputs/influxdb_listener_v2/README.md

plugins/inputs/influxdb_listener/http_listener.go

@@ -91,7 +91,7 @@ const sampleConfig = `
   ## 0 means to use the default of 65536 bytes (64 kibibytes)
   max_line_size = 0
 
-  ## Set one or more allowed client CA certificate file names to 
+  ## Set one or more allowed client CA certificate file names to
   ## enable mutually authenticated TLS connections
   tls_allowed_cacerts = ["/etc/telegraf/clientca.pem"]
 
@@ -420,10 +420,17 @@ func getPrecisionMultiplier(precision string) time.Duration {
 }
 
 func init() {
+	// http_listener deprecated in 1.9
 	inputs.Add("http_listener", func() telegraf.Input {
 		return &HTTPListener{
 			ServiceAddress: ":8186",
 			TimeFunc:       time.Now,
 		}
 	})
+	inputs.Add("influxdb_listener", func() telegraf.Input {
+		return &HTTPListener{
+			ServiceAddress: ":8186",
+			TimeFunc:       time.Now,
+		}
+	})
 }