title: Generic JSON API: status and response time of an endpoint
agents: json_api
catalog: app
license: GPLv2
distribution: https://github.com/otAAAh/checkmk-json-agent
description:
 This check works together with the {Generic JSON API} special agent and needs
 no field configuration at all: every endpoint in the rule gets one service
 reporting the {request} rather than the data in the response.

 While it succeeds, the service is {OK} and reports the HTTP status code, the
 response time and the response size; the URL (and, when a redirect moved the
 request, the final URL) are shown in the details. The response time is measured
 from sending the request until the whole response body has been read, and is
 exposed as a metric; it is only checked against levels once you configure them.

 For an {HTTPS} endpoint with certificate verification enabled, the TLS
 certificate's remaining validity is also reported, in days, as a metric with
 optional lower levels. It is read from the connection the agent already makes,
 so it costs no extra request and needs no second check against the same URL.
 When it cannot be read - plain HTTP, verification turned off, or a connection
 reused from the pool - nothing about the certificate is reported; that is
 {absent}, not {expired}, and never causes an alert.

 When the request fails outright - connection refused, a TLS error, a timeout,
 an HTTP status that the rule does not accept, or a response that is not JSON -
 the service is {CRIT} and reports the error. That state is configurable, so an
 endpoint that is allowed to be unavailable can be a mere {WARN}.

 When the endpoint has a cache TTL configured and its last response is still
 young enough, the agent serves that instead of making a request. The service
 then reports {from cache} with the body's age and records no response time,
 because no request was made; a failing request is never answered from an
 expired cache, so a real outage still shows up.

 When the endpoint follows the API's {pagination}, this service reports how many
 pages were read and how many elements the merged collection ended up with. If a
 further page existed but was not read - a page or element limit was reached, or
 the API offered a next link the agent refuses to follow, such as one on another
 host - the service says the collection is {incomplete} and goes {WARN} (also
 configurable). That matters because every service built from that collection, a
 count or an aggregation or a wildcard, is then describing only part of it. A
 page that cannot be read at all fails the endpoint instead, so half a collection
 is never reported as if it were whole.

 The endpoint can also be configured to report the {raw response} in this
 service's details: the body as it came off the wire, cut off at a configurable
 number of bytes, and optionally the response headers. It covers a rejected
 response too - an unexpected HTTP status, or a body that is not JSON - which is
 where an API usually explains itself, and the body of such a response is only
 read when this is switched on. Credentials are stripped first: {Set-Cookie} and
 any authorization header are masked, and the endpoint's own secret is removed
 wherever it appears. Everything else is reported verbatim, and these details are
 stored with every check result, so it is off by default and should stay off for
 a response carrying sensitive data. The details always describe the most recent
 check; nothing is archived.

 Configure the levels for the response time, the levels for the certificate's
 remaining validity, and the states for an unreachable endpoint and for an
 incompletely read collection with the check parameters rule
 {Generic JSON API endpoint} (Setup >
 Service monitoring rules > Applications). The endpoint's connection settings -
 and its optional name - live in the {Generic JSON API} special agent rule.

 If you do not want these services, remove them the standard way with a
 "Disabled services" rule.

 An endpoint that prefixes its field service names with its own name gets this
 same service under a name that sorts with the services it describes, {JSON
 <endpoint> API}, from the sibling plugin {json_api_endpoint_prefixed}. Every
 endpoint is discovered by exactly one of the two.

item:
 The name configured for the endpoint, or its URL when it has no name. The URL
 is used without its query string, so a credential passed as a query parameter
 stays out of the service description; the full URL is in the service details.

discovery:
 One service is created for each endpoint configured in the special agent rule.
