pmjsonPrint(3)

1PMJSONGET(3)               Library Functions Manual               PMJSONGET(3)
2
3
4

NAME

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

C SYNOPSIS

10       #include <pcp/pmapi.h>
11       #include <pcp/pmjson.h>
12
13       typedef int (*json_get)(void *buffer, int length, void *data);
14       int pmjsonGet(json_metric_desc *json_metrics, int nmetrics, pmInDom
15               indom, json_get callback, void *data);
16       int pmjsonPrint(FILE *fp, json_flag *output_flags, const char
17               *json_pointer, json_get callback, void *data);
18
19       int pmjsonInit(int fd, json_metric_desc *json_metrics, int nmetrics);
20       int  pmjsonInitIndom(int  fd,   json_metric_desc   *json_metrics,   int
21               nmetrics, pmInDom indom);
22
23       cc ... -lpcp_web
24

DESCRIPTION

26       pmjsonGet performs metric value extraction from JSON strings for a Per‐
27       formance Metric Domain Agent (PMDA(3)).  Metrics and instances are  de‐
28       fined  by the json_metrics parameter.  The result of parsing is the ex‐
29       traction of values  for  the  requested  metrics  (as  defined  in  the
30       json_pointer field) in the values field.
31
32       A  simple diagnostic utility for reporting JSON strings iss provided as
33       a convenience as well.  Its output_flags argument allows it to  support
34       a  variety  of alternate output formats, including minimal JSON (no op‐
35       tional whitespace), pretty-printed, and a simple YAML subset.
36
37       json_metrics is the array of json_metric_desc struct which contains the
38       json  pointer  to  the  metric  data,  possible flags to check the data
39       against, number of values (in the case of an array), pmAtomValue  where
40       the data is stored, as well as the instance domain in the event the PM‐
41       DA has multiple instance  domains.   The  number  of  elements  in  the
42       json_metrics array is indicated by the nmetrics parameter.
43
44       Interfaces  for common cases are provided - pmjsonInit specifies a call
45       to the JSON parsing and metric  value  extraction  functionality  where
46       there  are  no instance domains (or the PMDA wishes to perform instance
47       domain operations itself) and where data can be read directly  from  an
48       open file descriptor.  pmjsonInitIndom is similar, but makes use of the
49       pmdaCacheAdd(3) function where possible.
50
51       The JSON string must be provided by the callback function.  This  func‐
52       tion  is passed a memory buffer of length bytes and an opaque user data
53       pointer which is unchanged from the original call to pmjsonGet or  pmj‐
54       sonPrint.  The returned result must be the number of bytes written into
55       buffer, zero when no more data is available or less than zero on  error
56       conditions.
57
58       indom is the instance domain to be passed to pmdaCacheAdd.
59
60            typedef struct json_metrics_desc {
61                char          *json_pointer;  /* json pointer to metric */
62                int           flags;          /* flags to check if set */
63                int           num_values;     /* number of values */
64                pmAtomValue   values;         /* metric value */
65                char          *dom;           /* instance domain */
66            } json_metric_desc;
67
68       The JSON Pointer syntax current follows RFC6901 in specifying a metrics
69       location within the JSON document.
70

EXAMPLE

72       For the sample JSON document:
73
74       {
75           "Name": "/clever_almeida",
76           "State": {
77               "Dead": false,
78               "Error": "",
79               "ExitCode": 0,
80               "FinishedAt": "2016-07-18T21:21:20.332488706Z",
81               "OOMKilled": false,
82               "Paused": false,
83               "Pid": 0,
84               "Restarting": false,
85               "Running": false,
86               "StartedAt": "2016-07-18T14:10:58.52487316Z"
87           }
88       }
89
90       A possible corresponding json_metric array would be as follows for  the
91       Pid,  Name,  and  metrics to indicate whether the container is Running,
92       Paused, or Restarting.
93
94       static json_metric_desc json_metrics[] = {
95           { "State/Pid", 0, 1, {0}, ""},
96           { "Name", 0, 1, {0}, ""},
97           { "State/Running", CONTAINER_FLAG_RUNNING, 1, {0}, ""},
98           { "State/Paused", CONTAINER_FLAG_PAUSED, 1, {0}, ""},
99           { "State/Restarting", CONTAINER_FLAG_RESTARTING, 1, {0}, ""},
100       };
101

RETURN CODE

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

NAME

C SYNOPSIS

DESCRIPTION

EXAMPLE

RETURN CODE

SEE ALSO