http_response

README

HTTP Response Input Plugin

This input plugin checks HTTP/HTTPS connections.

Global configuration options

In addition to the plugin-specific configuration settings, plugins support additional global and plugin configuration settings. These settings are used to modify metrics, tags, and field or create aliases and configure ordering, etc. See the CONFIGURATION.md for more details.

Secret-store support

This plugin supports secrets from secret-stores for the username and password option. See the secret-store documentation for more details on how to use them.

Configuration

# HTTP/HTTPS request given an address a method and a timeout
[[inputs.http_response]]
  ## List of urls to query.
  # urls = ["http://localhost"]

  ## Set http_proxy.
  ## Telegraf uses the system wide proxy settings if it's is not set.
  # http_proxy = "http://localhost:8888"

  ## Set response_timeout (default 5 seconds)
  # response_timeout = "5s"

  ## HTTP Request Method
  # method = "GET"

  ## Whether to follow redirects from the server (defaults to false)
  # follow_redirects = false

  ## Optional file with Bearer token
  ## file content is added as an Authorization header
  # bearer_token = "/path/to/file"

  ## Optional HTTP Basic Auth Credentials
  # username = "username"
  # password = "pa$$word"

  ## Optional HTTP Request Body
  # body = '''
  # {'fake':'data'}
  # '''

  ## Optional HTTP Request Body Form
  ## Key value pairs to encode and set at URL form. Can be used with the POST
  ## method + application/x-www-form-urlencoded content type to replicate the
  ## POSTFORM method.
  # body_form = { "key": "value" }

  ## Optional name of the field that will contain the body of the response.
  ## By default it is set to an empty String indicating that the body's
  ## content won't be added
  # response_body_field = ''

  ## Maximum allowed HTTP response body size in bytes.
  ## 0 means to use the default of 32MiB.
  ## If the response body size exceeds this limit a "body_read_error" will
  ## be raised.
  # response_body_max_size = "32MiB"

  ## Optional substring or regex match in body of the response (case sensitive)
  # response_string_match = "\"service_status\": \"up\""
  # response_string_match = "ok"
  # response_string_match = "\".*_status\".?:.?\"up\""

  ## Expected response status code.
  ## The status code of the response is compared to this value. If they match,
  ## the field "response_status_code_match" will be 1, otherwise it will be 0.
  ## If the expected status code is 0, the check is disabled and the field
  ## won't be added.
  # response_status_code = 0

  ## Optional TLS Config
  # tls_ca = "/etc/telegraf/ca.pem"
  # tls_cert = "/etc/telegraf/cert.pem"
  # tls_key = "/etc/telegraf/key.pem"
  ## Use TLS but skip chain & host verification
  # insecure_skip_verify = false
  ## Use the given name as the SNI server name on each URL
  # tls_server_name = ""
  ## TLS renegotiation method, choose from "never", "once", "freely"
  # tls_renegotiation_method = "never"

  ## HTTP Request Headers (all values must be strings)
  # [inputs.http_response.headers]
  #   Host = "github.com"

  ## Optional setting to map response http headers into tags
  ## If the http header is not present on the request, no corresponding tag will
  ## be added. If multiple instances of the http header are present, only the
  ## first value will be used.
  # http_header_tags = {"HTTP_HEADER" = "TAG_NAME"}

  ## Interface to use when dialing an address
  # interface = "eth0"

  ## Optional Cookie authentication
  # cookie_auth_url = "https://localhost/authMe"
  # cookie_auth_method = "POST"
  # cookie_auth_username = "username"
  # cookie_auth_password = "pa$$word"
  # cookie_auth_body = '{"username": "user", "password": "pa$$word", "authenticate": "me"}'
  ## cookie_auth_renewal not set or set to "0" will auth once and never renew the cookie
  # cookie_auth_renewal = "5m"

Metrics

• http_response
  • tags:
    • server (target URL)
    • method (request method)
    • status_code (response status code)
    • result (see below)
  • fields:
    • response_time (float, seconds)
    • content_length (int, response body length)
    • response_string_match (int, 0 = mismatch / body read error, 1 = match)
    • response_status_code_match (int, 0 = mismatch, 1 = match)
    • http_response_code (int, response status code)
    • result_type (string, deprecated in 1.6: use result tag and result_code field)
    • result_code (int, see below)

result / result_code

Upon finishing polling the target server, the plugin registers the result of the operation in the result tag, and adds a numeric field called result_code corresponding with that tag value.

This tag is used to expose network and plugin errors. HTTP errors are considered a successful connection.

Tag value	Corresponding field value	Description
success	0	The HTTP request completed, even if the HTTP code represents an error
response_string_mismatch	1	The option response_string_match was used, and the body of the response didn't match the regex. HTTP errors with content in their body (like 4xx, 5xx) will trigger this error
body_read_error	2	The option response_string_match was used, but the plugin wasn't able to read the body of the response. Responses with empty bodies (like 3xx, HEAD, etc) will trigger this error. Or the option response_body_field was used and the content of the response body was not a valid utf-8. Or the size of the body of the response exceeded the response_body_max_size
connection_failed	3	Catch all for any network error not specifically handled by the plugin
timeout	4	The plugin timed out while awaiting the HTTP connection to complete
dns_error	5	There was a DNS error while attempting to connect to the host
response_status_code_mismatch	6	The option response_status_code_match was used, and the status code of the response didn't match the value.

Example Output

http_response,method=GET,result=success,server=http://github.com,status_code=200 content_length=87878i,http_response_code=200i,response_time=0.937655534,result_code=0i,result_type="success" 1565839598000000000

Optional Cookie Authentication Settings

The optional Cookie Authentication Settings will retrieve a cookie from the given authorization endpoint, and use it in subsequent API requests. This is useful for services that do not provide OAuth or Basic Auth authentication, e.g. the Tesla Powerwall API, which uses a Cookie Auth Body to retrieve an authorization cookie. The Cookie Auth Renewal interval will renew the authorization by retrieving a new cookie at the given interval.

Documentation

Index

• type HTTPResponse
  • func (h *HTTPResponse) Gather(acc telegraf.Accumulator) error
  • func (h *HTTPResponse) Init() error
  • func (*HTTPResponse) SampleConfig() string

Types

type HTTPResponse

type HTTPResponse struct {
	Address         string              `toml:"address" deprecated:"1.12.0;1.35.0;use 'urls' instead"`
	URLs            []string            `toml:"urls"`
	HTTPProxy       string              `toml:"http_proxy"`
	Body            string              `toml:"body"`
	BodyForm        map[string][]string `toml:"body_form"`
	Method          string              `toml:"method"`
	ResponseTimeout config.Duration     `toml:"response_timeout"`
	HTTPHeaderTags  map[string]string   `toml:"http_header_tags"`
	Headers         map[string]string   `toml:"headers"`
	FollowRedirects bool                `toml:"follow_redirects"`
	// Absolute path to file with Bearer token
	BearerToken         string      `toml:"bearer_token"`
	ResponseBodyField   string      `toml:"response_body_field"`
	ResponseBodyMaxSize config.Size `toml:"response_body_max_size"`
	ResponseStringMatch string      `toml:"response_string_match"`
	ResponseStatusCode  int         `toml:"response_status_code"`
	Interface           string      `toml:"interface"`
	// HTTP Basic Auth Credentials
	Username config.Secret `toml:"username"`
	Password config.Secret `toml:"password"`
	tls.ClientConfig
	cookie.CookieAuthConfig

	Log telegraf.Logger `toml:"-"`
	// contains filtered or unexported fields
}

HTTPResponse struct

func (*HTTPResponse) Gather

func (h *HTTPResponse) Gather(acc telegraf.Accumulator) error

Gather gets all metric fields and tags and returns any errors it encounters

func (*HTTPResponse) Init

func (h *HTTPResponse) Init() error

func (*HTTPResponse) SampleConfig

func (*HTTPResponse) SampleConfig() string