---
name: "pmjsonGet"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmjsonGet"
---

# pmjsonGet(3)

JSON string helpers and metrics extraction

## 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)](/PMDA/3.md)). 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 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. 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 directly from an open file descriptor. **pmjsonInitIndom** is similar, but makes use of the [**pmdaCacheStore**(3)](/pmdaCacheStore/3.md) 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)](/pmErrStr_r/3.md) is returned.

## SEE ALSO

[**PMDA**(3)](/PMDA/3.md), [**pmErrStr\_r**(3)](/pmErrStr_r/3.md), [**pmdaCacheStore**(3)](/pmdaCacheStore/3.md), **https://www.json.org/**, **https://tools.ietf.org/html/rfc7159**, and **https://tools.ietf.org/html/rfc6901**.