HTTP

Access to HTTP (and HTTPS) endpoints is provided by the http() function.

http(url[, method='GET'][, timeout=10][, max_retries=0][, verify=True][, oauth2=False][, allow_redirects=None][, headers=None])
Parameters:
  • url (str) – The URL that is to be queried. See below for details.
  • method (str) – The HTTP request method. Allowed values are GET or HEAD.
  • timeout (float) – The timeout for the HTTP request, in seconds. Defaults to 10.
  • max_retries (int) – The number of times the HTTP request should be retried if it fails. Defaults to 0.
  • verify (bool) – Can be set to False to disable SSL certificate verification.
  • oauth2 (bool) – Can be set to True to inject a OAuth 2 Bearer access token in the outgoing request
  • oauth2_token_name (str) – The name of the OAuth 2 token. Default is uid.
  • allow_redirects (bool) – Follow request redirects. If None then it will be set to True in case of GET and False in case of HEAD request.
  • headers (dict) – The headers to be used in the HTTP request.
Returns:

An object encapsulating the response from the server. See below.

For checks on entities that define the attributes url or host, the given URL may be relative. In that case, the URL http://<value><url> is queried, where <value> is the value of that attribute, and <url> is the URL passed to this function. If an entity defines both url and host, the former is used.

This function cannot query URLs using a scheme other than HTTP or HTTPS; URLs that do not start with http:// or https:// are considered to be relative.

Example:

http('http://www.example.org/data?fetch=json').json()

# avoid raising error in case the response error status (e.g. 500 or 503)
# but you are interested in the response json
http('http://www.example.org/data?fetch=json').json(raise_error=False)

HTTP Responses

The object returned by the http() function provides methods: json(), text(), headers(), cookies(), content_size(), time() and code().

json(raise_error=True)

This method returns an object representing the content of the JSON response from the queried endpoint. Usually, this will be a map (represented by a Python dict), but, depending on the endpoint, it may also be a list, string, set, integer, floating-point number, or Boolean.

text(raise_error=True)

Returns the text response from queried endpoint:

http("/heartbeat.jsp", timeout=5).text().strip()=='OK: JVM is running'

Since we’re using a relative url, this check has to be defined for specific entities (e.g. type=zomcat will run it on all zomcat instances). The strip function removes all leading and trailing whitespace.

headers(raise_error=True)

Returns the response headers in a case-insensitive dict-like object:

http("/api/json", timeout=5).headers()['content-type']=='application/json'
cookies(raise_error=True)

Returns the response cookies in a dict like object:

http("/heartbeat.jsp", timeout=5).cookies()['my_custom_cookie'] == 'custom_cookie_value'
content_size(raise_error=True)

Returns the length of the response content:

http("/heartbeat.jsp", timeout=5).content_size() > 1024
time(raise_error=True)

Returns the elapsed time in seconds until response was received:

http("/heartbeat.jsp", timeout=5).time() > 1.5
code()

Return HTTP status code from the queried endpoint.:

http("/heartbeat.jsp", timeout=5).code()
actuator_metrics(prefix='zmon.response.', raise_error=True)

Parses the json result of a metrics endpoint into a map ep->method->status->metric

http(“/metrics”, timeout=5).actuator_metrics()
prometheus()

Parse the resulting text result according to the Prometheus specs using their prometheus_client.

http(“/metrics”, timeout=5).prometheus()
prometheus_flat()

Parse the resulting text result according to the Prometheus specs using their prometheus_client and flattens the outcome.

http(“/metrics”, timeout=5).prometheus_flat()
jolokia(read_requests, raise_error=False)

Does a POST request to the endpoint given in the wrapper, with validating the endpoint and setting the request to be read-only.

Parameters:
Returns:

Jolokia response

Example:

requests = [
    {'mbean': 'org.apache.cassandra.metrics:type=ClientRequest,scope=Read,name=Latency'},
    {'mbean': 'org.apache.cassandra.metrics:type=ClientRequest,scope=Write,name=Latency'},
]
results = http('http://{}:8778/jolokia/'.format(entity['ip']), timeout=15).jolokia(requests)