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.

 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.

 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.

 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.

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