NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | RETURN CODE | SEE ALSO | COLOPHON

PMJSONGET(3)              Library Functions Manual              PMJSONGET(3)

NAME         top

       pmjsonGet,  pmjsonInit,  pmjsonInitIndom  -  JSON performance metrics
       extraction

C SYNOPSIS         top

       #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 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         top

       pmjsonGet performs metric value extraction from JSON strings for a
       Performance Metric Domain Agent (PMDA(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.

       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
       instance domain operations itself) and where data can be read
       directly from an open file descriptor.  pmjsonInitIndom 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.
       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 document.

EXAMPLE         top

       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         top

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

SEE ALSO         top

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

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@oss.sgi.com.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2017-09-15.  If you discover any rendering problems in this HTML ver‐
       sion of the page, or you believe there is a better or more up-to-date
       source for the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original man‐
       ual page), send a mail to man-pages@man7.org

Performance Co-Pilot                 PCP                        PMJSONGET(3)

Pages that refer to this page: pmhttpnewclient(3)