Skip to content

Commit

Permalink
Update httpjson documentation (#2619)
Browse files Browse the repository at this point in the history 
closes  #2536
  • Loading branch information
@danielnelson
danielnelson authored Apr 4, 2017
1 parent f2805fd commit 8bf193d
Show file tree
Hide file tree
Showing 3 changed files with 77 additions and 143 deletions.
2 changes: 1 addition & 1 deletion plugins/inputs/EXAMPLE_README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The example plugin gathers metrics about example things
- tag2
- measurement2 has the following tags:
- tag3

### Sample Queries:

These are some useful queries (to generate dashboards or other) to run against data from this plugin:
Expand Down
201 changes: 65 additions & 136 deletions plugins/inputs/httpjson/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,174 +1,110 @@
# HTTP JSON Plugin
# HTTP JSON Input Plugin

The httpjson plugin can collect data from remote URLs which respond with JSON. Then it flattens JSON and finds all numeric values, treating them as floats.
The httpjson plugin collects data from HTTP URLs which respond with JSON. It flattens the JSON and finds all numeric values, treating them as floats.

For example, if you have a service called _mycollector_, which has HTTP endpoint for gathering stats at http://my.service.com/_stats, you would configure the HTTP JSON plugin like this:
### Configuration:

```
```toml
[[inputs.httpjson]]
name = "mycollector"
## NOTE This plugin only reads numerical measurements, strings and booleans
## will be ignored.

## Name for the service being polled. Will be appended to the name of the
## measurement e.g. "httpjson_webserver_stats".
##
## Deprecated (1.3.0): Use name_override, name_suffix, name_prefix instead.
name = "webserver_stats"

## URL of each server in the service's cluster
servers = [
"http://my.service.com/_stats"
"http://localhost:9999/stats/",
"http://localhost:9998/stats/",
]
# HTTP method to use (case-sensitive)
method = "GET"
# Set response_timeout (default 5 seconds)
## Set response_timeout (default 5 seconds)
response_timeout = "5s"
```

`name` is used as a prefix for the measurements.

`method` specifies HTTP method to use for requests.
## HTTP method to use: GET or POST (case-sensitive)
method = "GET"

`response_timeout` specifies timeout to wait to get the response
## Tags to extract from top-level of JSON server response.
# tag_keys = [
# "my_tag_1",
# "my_tag_2"
# ]

You can also specify which keys from server response should be considered tags:
## HTTP Request Parameters (all values must be strings). For "GET" requests, data
## will be included in the query. For "POST" requests, data will be included
## in the request body as "x-www-form-urlencoded".
# [inputs.httpjson.parameters]
# event_type = "cpu_spike"
# threshold = "0.75"

```
[[inputs.httpjson]]
...
## HTTP Request Headers (all values must be strings).
# [inputs.httpjson.headers]
# X-Auth-Token = "my-xauth-token"
# apiVersion = "v1"

tag_keys = [
"role",
"version"
]
## Optional SSL Config
# ssl_ca = "/etc/telegraf/ca.pem"
# ssl_cert = "/etc/telegraf/cert.pem"
# ssl_key = "/etc/telegraf/key.pem"
## Use SSL but skip chain & host verification
# insecure_skip_verify = false
```

If the JSON response is an array of objects, then each object will be parsed with the same configuration.
### Measurements & Fields:

You can also specify additional request parameters for the service:
- httpjson
- response_time (float): Response time in seconds

```
[[inputs.httpjson]]
...
Additional fields are dependant on the response of the remote service being polled.

[inputs.httpjson.parameters]
event_type = "cpu_spike"
threshold = "0.75"
### Tags:

```
- All measurements have the following tags:
- server: HTTP origin as defined in configuration as `servers`.

You can also specify additional request header parameters for the service:
Any top level keys listed under `tag_keys` in the configuration are added as tags. Top level keys are defined as keys in the root level of the object in a single object response, or in the root level of each object within an array of objects.

```
[[inputs.httpjson]]
...

[inputs.httpjson.headers]
X-Auth-Token = "my-xauth-token"
apiVersion = "v1"
```
### Examples Output:

# Example:
This plugin understands responses containing a single JSON object, or a JSON Array of Objects.

Let's say that we have a service named "mycollector" configured like this:

```
[[inputs.httpjson]]
name = "mycollector"
servers = [
"http://my.service.com/_stats"
]
# HTTP method to use (case-sensitive)
method = "GET"
tag_keys = ["service"]
```

which responds with the following JSON:
**Object Output:**

Given the following response body:
```json
{
"service": "service01",
"a": 0.5,
"b": {
"c": "some text",
"d": 0.1,
"e": 5
}
},
"service": "service01"
}
```
The following metric is produced:

The collected metrics will be:
```
httpjson_mycollector_a,service='service01',server='http://my.service.com/_stats' value=0.5
httpjson_mycollector_b_d,service='service01',server='http://my.service.com/_stats' value=0.1
httpjson_mycollector_b_e,service='service01',server='http://my.service.com/_stats' value=5
```

# Example 2, Multiple Services:
`httpjson,server=http://localhost:9999/stats/ b_d=0.1,a=0.5,b_e=5,response_time=0.001`

There is also the option to collect JSON from multiple services, here is an example doing that.
Note that only numerical values are extracted and the type is float.

```
[[inputs.httpjson]]
name = "mycollector1"
servers = [
"http://my.service1.com/_stats"
]
# HTTP method to use (case-sensitive)
method = "GET"
If `tag_keys` is included in the configuration:

```toml
[[inputs.httpjson]]
name = "mycollector2"
servers = [
"http://service.net/json/stats"
]
# HTTP method to use (case-sensitive)
method = "POST"
```

The services respond with the following JSON:

mycollector1:
```json
{
"a": 0.5,
"b": {
"c": "some text",
"d": 0.1,
"e": 5
}
}
```

mycollector2:
```json
{
"load": 100,
"users": 1335
}
tag_keys = ["service"]
```

The collected metrics will be:
Then the `service` tag will also be added:

```
httpjson_mycollector1_a,server='http://my.service.com/_stats' value=0.5
httpjson_mycollector1_b_d,server='http://my.service.com/_stats' value=0.1
httpjson_mycollector1_b_e,server='http://my.service.com/_stats' value=5
`httpjson,server=http://localhost:9999/stats/,service=service01 b_d=0.1,a=0.5,b_e=5,response_time=0.001`

httpjson_mycollector2_load,server='http://service.net/json/stats' value=100
httpjson_mycollector2_users,server='http://service.net/json/stats' value=1335
```
**Array Output:**

# Example 3, Multiple Metrics in Response:

The response JSON can be treated as an array of data points that are all parsed with the same configuration.

```
[[inputs.httpjson]]
name = "mycollector"
servers = [
"http://my.service.com/_stats"
]
# HTTP method to use (case-sensitive)
method = "GET"
tag_keys = ["service"]
```

which responds with the following JSON:
If the service returns an array of objects, one metric is be created for each object:

```json
[
Expand All @@ -193,12 +129,5 @@ which responds with the following JSON:
]
```

The collected metrics will be:
```
httpjson_mycollector_a,service='service01',server='http://my.service.com/_stats' value=0.5
httpjson_mycollector_b_d,service='service01',server='http://my.service.com/_stats' value=0.1
httpjson_mycollector_b_e,service='service01',server='http://my.service.com/_stats' value=5
httpjson_mycollector_a,service='service02',server='http://my.service.com/_stats' value=0.6
httpjson_mycollector_b_d,service='service02',server='http://my.service.com/_stats' value=0.2
httpjson_mycollector_b_e,service='service02',server='http://my.service.com/_stats' value=6
```
`httpjson,server=http://localhost:9999/stats/,service=service01 a=0.5,b_d=0.1,b_e=5,response_time=0.003`
`httpjson,server=http://localhost:9999/stats/,service=service02 a=0.6,b_d=0.2,b_e=6,response_time=0.003`
17 changes: 11 additions & 6 deletions plugins/inputs/httpjson/httpjson.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,10 @@ var sampleConfig = `
## NOTE This plugin only reads numerical measurements, strings and booleans
## will be ignored.
## a name for the service being polled
## Name for the service being polled. Will be appended to the name of the
## measurement e.g. httpjson_webserver_stats
##
## Deprecated (1.3.0): Use name_override, name_suffix, name_prefix instead.
name = "webserver_stats"
## URL of each server in the service's cluster
Expand All @@ -93,12 +96,14 @@ var sampleConfig = `
# "my_tag_2"
# ]
## HTTP parameters (all values must be strings)
[inputs.httpjson.parameters]
event_type = "cpu_spike"
threshold = "0.75"
## HTTP parameters (all values must be strings). For "GET" requests, data
## will be included in the query. For "POST" requests, data will be included
## in the request body as "x-www-form-urlencoded".
# [inputs.httpjson.parameters]
# event_type = "cpu_spike"
# threshold = "0.75"
## HTTP Header parameters (all values must be strings)
## HTTP Headers (all values must be strings)
# [inputs.httpjson.headers]
# X-Auth-Token = "my-xauth-token"
# apiVersion = "v1"
Expand Down

0 comments on commit 8bf193d

Please sign in to comment.