# pmjsonget

## 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 (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.
    
           A simple diagnostic utility for reporting JSON strings is provided
           as a convenience as well.  Its _output_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 con‐
           tains 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 do‐
           main 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 di‐
           rectly 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



           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.
    


* * *