|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | DESCRIPTION | EXAMPLE | RETURN CODE | SEE ALSO | COLOPHON |
|
|
|
PMJSONGET(3) Library Functions Manual PMJSONGET(3)
pmjsonGet, pmjsonPrint, pmjsonInit, pmjsonInitIndom - JSON string
helpers and metrics extraction
#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
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.
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}, ""},
};
The functions return zero on success, otherwise an error code
suitable for passing to pmErrStr_r(3) is returned.
PMDA(3), pmErrStr_r(3), pmdaCacheStore(3), https://www.json.org/ ,
https://tools.ietf.org/html/rfc7159 , and
https://tools.ietf.org/html/rfc6901 .
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)
|
HTML rendering created 2024-06-26 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|