NAME

       pmjsonGet, pmjsonPrint, pmjsonInit, pmjsonInitIndom - JSON string helpers and metrics extraction

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/pmjson.h>

       typedef int (*json_get)(void *buffer, int length, void *data);
       int pmjsonGet(json_metric_desc *json_metrics, int nmetrics, pmInDom indom, json_get callback, void
               *data);
       int pmjsonPrint(FILE *fp, json_flag *output_flags, const char *json_pointer, json_get callback, void
               *data);

       int pmjsonInit(int fd, json_metric_desc *json_metrics, int nmetrics);
       int pmjsonInitIndom(int fd, json_metric_desc *json_metrics, int nmetrics, pmInDom indom);

       cc ... -lpcp_web

DESCRIPTION

       pmjsonGet  performs  metric value extraction from JSON strings for a Performance Metric Domain Agent (PM‐
       DA(3)).  Metrics and instances are defined by the json_metrics parameter.  The result of parsing  is  the
       extraction  of  values  for  the  requested  metrics (as defined in the json_pointer field) in the values
       field.

       A simple diagnostic utility for reporting JSON strings iss provided as a convenience as well.   Its  out‐
       put_flags argument allows it to support a variety of alternate output formats, including minimal JSON (no
       optional whitespace), pretty-printed, and a simple YAML subset.

       json_metrics  is the array of json_metric_desc struct which contains the json pointer to the metric data,
       possible flags to check the data against, number of values (in the case of an array),  pmAtomValue  where
       the  data  is stored, as well as the instance domain in the event the PMDA has multiple instance domains.
       The number of elements in the json_metrics array is indicated by the nmetrics parameter.

       Interfaces for common cases are provided - pmjsonInit specifies a call to the  JSON  parsing  and  metric
       value  extraction  functionality  where  there are no instance domains (or the PMDA wishes to perform in‐
       stance domain operations itself) and where data can be read directly from an open file descriptor.   pmj‐
       sonInitIndom is similar, but makes use of the pmdaCacheAdd(3) function where possible.

       The  JSON  string  must be provided by the callback function.  This function is passed a memory buffer of
       length bytes and an opaque user data pointer which is unchanged from the original call  to  pmjsonGet  or
       pmjsonPrint.  The returned result must be the number of bytes written into buffer, zero when no more data
       is available or less than zero on error conditions.

       indom is the instance domain to be passed to pmdaCacheAdd.

            typedef struct json_metrics_desc {
                char          *json_pointer;  /* json pointer to metric */
                int           flags;          /* flags to check if set */
                int           num_values;     /* number of values */
                pmAtomValue   values;         /* metric value */
                char          *dom;           /* instance domain */
            } json_metric_desc;

       The  JSON  Pointer  syntax current follows RFC6901 in specifying a metrics location within the JSON docu‐
       ment.

EXAMPLE

       For the sample JSON document:

       {
           "Name": "/clever_almeida",
           "State": {
               "Dead": false,
               "Error": "",
               "ExitCode": 0,
               "FinishedAt": "2016-07-18T21:21:20.332488706Z",
               "OOMKilled": false,
               "Paused": false,
               "Pid": 0,
               "Restarting": false,
               "Running": false,
               "StartedAt": "2016-07-18T14:10:58.52487316Z"
           }
       }

       A possible corresponding json_metric array would be as follows for the Pid, Name, and metrics to indicate
       whether the container is Running, Paused, or Restarting.

       static json_metric_desc json_metrics[] = {
           { "State/Pid", 0, 1, {0}, ""},
           { "Name", 0, 1, {0}, ""},
           { "State/Running", CONTAINER_FLAG_RUNNING, 1, {0}, ""},
           { "State/Paused", CONTAINER_FLAG_PAUSED, 1, {0}, ""},
           { "State/Restarting", CONTAINER_FLAG_RESTARTING, 1, {0}, ""},
       };

RETURN CODE

       The functions return zero on success, otherwise an error code suitable for passing  to  pmErrStr_r(3)  is
       returned.

SEE ALSO

       PMDA(3),  pmErrStr_r(3), pmdaCacheAdd(3), https://www.json.org/, https://tools.ietf.org/html/rfc7159, and
       https://tools.ietf.org/html/rfc6901.

Performance Co-Pilot                                   PCP                                          PMJSONGET(3)