pmjsonget(3) — Linux manual page

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

PMJSONGET(3)            Library Functions Manual            PMJSONGET(3)

NAME         top

       pmjsonGet, pmjsonPrint, pmjsonInit, pmjsonInitIndom - JSON string
       helpers and 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 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         top

       pmjsonGet  performs metric value extraction from JSON strings for
       a Performance Metric Domain Agent  (PMDA(3)).   Metrics  and  in‐
       stances 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 is provid‐
       ed as a convenience as well.  Its output_flags argument allows it
       to support a variety of alternate output formats, including mini‐
       mal  JSON  (no optional whitespace), pretty-printed, and a simple
       YAML subset.

       json_metrics is the array of json_metric_desc struct  which  con‐
       tains  the  json  pointer  to  the metric data, possible flags to
       check the data against, number of values (in the case of  an  ar‐
       ray),  pmAtomValue  where  the data is stored, as well as the in‐
       stance domain in the event the PMDA  has  multiple  instance  do‐
       mains.  The number of elements in the json_metrics array is indi‐
       cated by the nmetrics parameter.

       Interfaces for common cases are provided - pmjsonInit specifies a
       call to the JSON parsing and metric value extraction functionali‐
       ty  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  pmdaCacheStore(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 pmdaCacheStore.

            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), pmdaCacheStore(3), https://www.json.org/ ,
       https://tools.ietf.org/html/rfc7159 ,                          and
       https://tools.ietf.org/html/rfc6901 .

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.  In‐
       formation about the project can be found at ⟨http://www.pcp.io/⟩.
       If  you  have  a  bug  report  for  this  manual page, send it to
       [email protected].   This  page  was  obtained  from  the   project's
       upstream                      Git                      repository
       ⟨https://github.com/performancecopilot/pcp.git⟩  on   2024-06-14.
       (At  that time, the date of the most recent commit that was found
       in the repository was 2024-06-14.)  If you discover any rendering
       problems in this HTML version 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 manual page), send a mail to
       [email protected]

Performance Co-Pilot               PCP                      PMJSONGET(3)

Pages that refer to this page: pmhttpnewclient(3)