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. That runtime name is also what the Gauge, Single metric and Bar chart
 dashboard widgets need: each is bound to one metric chosen BY NAME, and their
 dropdown only offers a service's real names once the widget is filtered to a
 host and a service. A field whose metric name has to be known in advance can
 state it in the rule; that costs the service its Perf-O-Meter, since every bar
 this plugin draws is declared against one of its own metrics. Two fields of one
 shared service that would resolve to the SAME metric name are rejected by
 Setup: the check can only disambiguate them by position, so reordering the
 fields would make two metrics trade histories. 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.
