title: Generic JSON API: monitor fields from any HTTP/JSON 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. The
 agent fetches one or more JSON documents over HTTP(S) and extracts the fields
 configured in the rule's endpoints. Each configured field becomes one service.

 A numeric value with configured levels is checked against those levels and
 exposed as a metric. A field may also carry an arithmetic transform (an
 expression on the variable {value}, e.g. {value / 1024 / 1024}) that is applied
 to the numeric value first, so the levels, the metric and the summary all use
 the transformed value; a broken expression or a non-finite result makes the
 service {UNKNOWN}.

 A field may instead aggregate a whole collection into one number: with the path
 pointing at an array or object (or at a {[*]} wildcard over the values), the
 service monitors the number of elements, or their sum, average, minimum or
 maximum. The result is a number, to which the unit, levels, transform and
 metric all apply; a path that holds neither an array nor an object makes the
 service {UNKNOWN}, as does an average, minimum or maximum over no elements at
 all (a sum over none is 0). With a {[*]} wildcard naming a field, every function
 - the count included - sees only the elements that actually have that field, so
 {nodes[*].load} counts the nodes reporting a load; if no element has it at all
 the service goes {UNKNOWN} rather than reporting an empty collection. A {[*]}
 wildcard or an aggregation may additionally be restricted with a filter, so that
 only the elements whose sub-field matches a condition (equals, does not equal,
 matches or does not match a regular expression) become services or are
 aggregated.

 Where the endpoint follows the API's {pagination}, all of this sees the merged
 collection - every page's elements, not just the first page's - so a count over
 a queue that pages at 25 reports the queue rather than the page size. If a
 further page existed but was not read, the collection is incomplete and the
 {endpoint's own} service says so; these services report the part that was read,
 with nothing in them to suggest it was cut short, which is why that notice
 belongs there and is a {WARN} by default.

 A {[*]} field may instead create one Checkmk {host} per element rather than one
 more service on the polling host: name a field within each element that holds
 the host name, and every element becomes a piggyback host carrying this service
 under its plain name. Only characters valid in a Checkmk host name are kept;
 anything else becomes an underscore. An element whose host field is missing
 keeps its service on the polling host, and so does everything outside the
 wildcard - including the endpoint's own service, which describes the request.
 The hosts must exist in Checkmk, or the piggyback data is stored and never
 monitored.

 A field may also be read as something other than a plain value. Read as a
 {counter}, the check monitors the change per second instead of the absolute
 total; the first check (and any check after the counter went backwards, e.g.
 because the monitored service restarted) cannot compute a rate yet and keeps
 the service's previous state. Read as a {timestamp} - Unix epoch seconds or
 milliseconds, or ISO 8601, auto-detected by default - the check monitors the
 age in seconds, so upper levels alert on stale data; a timestamp in the future
 yields a negative age, and an unparseable one makes the service {UNKNOWN}. The
 derived number is what the transform, the levels and the metric then use, and
 the raw reading stays visible in the service details.

 String matching offers two modes: a value can be required to fully match a
 regular expression, with a configurable state (default {CRIT}) when it does
 not; or the value can be mapped to a state by matching it against separate OK,
 WARN and CRIT regular expressions, tried in that order with the first full
 match winning and a configurable state (default {OK}) when none matches. It
 does not apply to a derived rate or age. Otherwise the value is shown in the
 service summary, and a metric is added when it is numeric.

 An endpoint can also be told to report the JSON a value was read from in its
 field services' details: the '[*]' element it came from (or the object holding
 it), or the whole response body, capped by a byte budget and stripped of the
 endpoint's credentials. The service that goes WARN or CRIT is the one that
 notifies, and a service's details reach notifications as $LONGSERVICEOUTPUT$ -
 so this is what puts the API's own answer in front of a person who often
 cannot reach the endpoint themselves. It is reported for a path that did not
 resolve as well.

 The service goes {UNKNOWN} if the configured path is not present in the
 response, or if its endpoint could not be reached or did not return JSON. By
 default only 2xx responses are read; additional HTTP status codes can be
 accepted per endpoint in the rule (so a health endpoint that answers with a
 non-2xx status and a JSON body can still be monitored). An endpoint failure is
 confined to that endpoint's own services.

 Configure it in Setup with the rule {Generic JSON API}. The levels and string
 matching a field carries there become the service's defaults; you can override
 them per folder, host or service with the check parameters rule {Generic JSON
 API} (Setup > Service monitoring rules > Applications) without touching the
 agent's connection settings.

 Several fields can also report into ONE service instead of one each: a field
 that names a shared service contributes a LINE to it rather than becoming a
 service, and the service's state is the worst of its lines - Checkmk's ordinary
 aggregation over the results a check yields. The field's own service name then
 names its line, and each line keeps its own levels, string matching, transform
 and unit. Because one service then holds several fields, a check parameters rule
 is not applied to such a service (one set of levels cannot describe several
 fields; the thresholds stay in the agent rule) and each line's metric is named
 after the line, which keeps their histories apart at the cost of the declared
 unit. A field written to the inventory instead of a service cannot report into a
 shared one.

 Two endpoints extracting the same fields would produce two services with the
 same name, the later one disambiguated with a {(2)} suffix that says nothing
 about which endpoint it came from. An endpoint can therefore be configured to
 prefix its field service names with its own name, so that {JSON Status} becomes
 {JSON <endpoint> Status} for that endpoint - including while the endpoint is
 failing, so a service does not rename itself when it goes bad. It needs an
 endpoint name; the URL is never used as a prefix. Enabling it renames the
 endpoint's services, which have to be discovered again.

 Every endpoint additionally gets a service of its own, {JSON API <name>}, which
 reports the request itself rather than the data in it - see its own man page.

item:
 The service name configured for the extracted field - or the name of the shared
 service, where fields report into one - behind the endpoint's name when the
 endpoint is configured to prefix its service names.

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