From 2d8cda02df64a1d313088efbc9cfe19f61f7c510 Mon Sep 17 00:00:00 2001 From: Daniel Nelson Date: Fri, 12 Oct 2018 14:20:12 -0700 Subject: [PATCH] Rename http_listener to influxdb_listener --- CHANGELOG.md | 12 ++++ README.md | 4 +- plugins/inputs/all/all.go | 2 +- plugins/inputs/http_listener/README.md | 48 ------------- plugins/inputs/http_listener_v2/README.md | 43 ++++++----- plugins/inputs/influxdb_listener/README.md | 67 ++++++++++++++++++ .../bufferpool.go | 0 .../http_listener.go | 9 ++- .../http_listener_test.go | 0 .../testdata/testmsgs.gz | Bin 10 files changed, 117 insertions(+), 68 deletions(-) delete mode 100644 plugins/inputs/http_listener/README.md create mode 100644 plugins/inputs/influxdb_listener/README.md rename plugins/inputs/{http_listener => influxdb_listener}/bufferpool.go (100%) rename plugins/inputs/{http_listener => influxdb_listener}/http_listener.go (98%) rename plugins/inputs/{http_listener => influxdb_listener}/http_listener_test.go (100%) rename plugins/inputs/{http_listener => influxdb_listener}/testdata/testmsgs.gz (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index b331369c8..880506fa4 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 647256f3e..c7f4be899 100644 --- a/README.md +++ b/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) diff --git a/plugins/inputs/all/all.go b/plugins/inputs/all/all.go index 909236c21..5840893e9 100644 --- a/plugins/inputs/all/all.go +++ b/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" diff --git a/plugins/inputs/http_listener/README.md b/plugins/inputs/http_listener/README.md deleted file mode 100644 index f1ff71f0a..000000000 --- a/plugins/inputs/http_listener/README.md +++ /dev/null @@ -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" -``` diff --git a/plugins/inputs/http_listener_v2/README.md b/plugins/inputs/http_listener_v2/README.md index 74532c90f..a2d5798dd 100644 --- a/plugins/inputs/http_listener_v2/README.md +++ b/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 diff --git a/plugins/inputs/influxdb_listener/README.md b/plugins/inputs/influxdb_listener/README.md new file mode 100644 index 000000000..38039c606 --- /dev/null +++ b/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 diff --git a/plugins/inputs/http_listener/bufferpool.go b/plugins/inputs/influxdb_listener/bufferpool.go similarity index 100% rename from plugins/inputs/http_listener/bufferpool.go rename to plugins/inputs/influxdb_listener/bufferpool.go diff --git a/plugins/inputs/http_listener/http_listener.go b/plugins/inputs/influxdb_listener/http_listener.go similarity index 98% rename from plugins/inputs/http_listener/http_listener.go rename to plugins/inputs/influxdb_listener/http_listener.go index cd82e40c0..29beff9a8 100644 --- a/plugins/inputs/http_listener/http_listener.go +++ b/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, + } + }) } diff --git a/plugins/inputs/http_listener/http_listener_test.go b/plugins/inputs/influxdb_listener/http_listener_test.go similarity index 100% rename from plugins/inputs/http_listener/http_listener_test.go rename to plugins/inputs/influxdb_listener/http_listener_test.go diff --git a/plugins/inputs/http_listener/testdata/testmsgs.gz b/plugins/inputs/influxdb_listener/testdata/testmsgs.gz similarity index 100% rename from plugins/inputs/http_listener/testdata/testmsgs.gz rename to plugins/inputs/influxdb_listener/testdata/testmsgs.gz