PMJSONGET(3)

💖 PMJSONGET(3) — Library Functions Manual 💖

okay bestie, gather round, because this one is a whole suite of functions from the Library Functions Manual and they are literally the moment JSON meets performance metrics. no cap.

✨ 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

link it like cc ... -lpcp_web and you're so back 💅

---

🦋 DESCRIPTION 🦋

so pmjsonGet is the main character here — it does metric value extraction from JSON strings for a Performance Metric Domain Agent (PMDA(3)). the metrics and instances you want? they're defined by the json_metrics parameter. and the result of parsing is literally the extraction of values for the requested metrics (as defined in the json_pointer field) living in the values field. iconic behaviour honestly.

there's also a little diagnostic utility for reporting JSON strings, provided as a convenience because the devs said "and what if we just... vibed". its output_flags argument lets it support a whole variety of alternate output formats, including:

• minimal JSON (no optional whitespace)
• pretty-printed
• a simple YAML subset

versatility? ate. 🔥

now 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

and the number of elements in the json_metrics array? that's what the nmetrics parameter is telling you. periodt.

---

🎀 the convenient interfaces 🎀

interfaces for common cases are provided, because they love us:

• 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. so chill.
• pmjsonInitIndom — similar, but makes use of the pmdaCacheStore(3) function where possible. fancy.

---

🌈 the callback, the whole callback, and nothing but the callback 🌈

the JSON string must be provided by the callback function. this function gets passed a memory buffer of length bytes and an opaque user data pointer which is unchanged from the original call to pmjsonGet or pmjsonPrint.

and the returned result? it must be:

• the number of bytes written into buffer
• zero when no more data is available
• less than zero on error conditions

like, get it right bestie, those are the only three moods. 😭

---

💜 indom 💜

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;

(yeah the struct tag is json_metrics_desc and the typedef is json_metric_desc, we don't make the rules, we just report them faithfully 🫶)

---

⭐ the JSON Pointer of it all ⭐

the JSON Pointer syntax currently follows RFC6901 in specifying a metrics location within the JSON document. iykyk.

---

🍓 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}, ""},
};

look at that little array go. she's doing so well. 👑

---

💀 RETURN CODE 💀

the functions return zero on success, otherwise an error code suitable for passing to pmErrStr_r(3) is returned. so if you get a nonzero, go hand it straight to pmErrStr_r(3) and let it explain the situation. no guesswork, no drama. 💅

---

🌟 SEE ALSO 🌟

• PMDA(3)
• pmErrStr_r(3)
• pmdaCacheStore(3)
• https://www.json.org/
• https://tools.ietf.org/html/rfc7159
• https://tools.ietf.org/html/rfc6901

---

and that's the whole page bestie, you're officially fluent 💖 this one's brought to you by Performance Co-Pilot — that's the PCP source and version, right there in the footer where it belongs — signing off on PMJSONGET(3) like the iconic little manpage it is. go forth and parse. ✨🦋🎀