BASIC OPERATION

pmdajson is a Performance Metrics Domain Agent (PMDA) which exports
metrics from arbitrary sources generating Javascript Object Notation
(JSON) syntax, describing metric metadata and values.

BASIC CONFIGURATION

PCP_PMDAS_DIR/json/config.json is used to define the JSON data sources
directories:

JSON sources that come from "directory_list" config file option are not
"trusted", and any command that needs to be run to get JSON data is run
as user "nobody".

JSON sources that come from "trusted_directory_list" config file option
are trusted, and any command that needs to be run to get JSON data is
run as user "root".

Example config.json:

  {
    "trusted_directory_list" : [ "/var/lib/pcp/pmdas/json/trusted" ]
  }

Note that the config.json config file is read once when the JSON pmda
starts. Every time metrics are refreshed, the directories listed in
the 'directory_list' and 'trusted_directory_list' config file options
are traversed, looking for new (and deleted) JSON data sources
(described below).

JSON DATA SOURCES

There are 2 sets of information needed for a particular JSON source: a
JSON metadata file and the associated JSON data file. The combination of
the JSON metadata file and JSON data is called a JSON source. pmdajson
exports the metrics for each JSON source as a separate hierarchy under
the JSON pmda.

For example, let us assume the following simple json.data file:

  {
    "string_value": "testing, 1, 2, 3",
    "read_count": 0
  }

The associated metadata.json file would look like the following:

  {
    "prefix" : "simple",
    "metrics": [
      {
        "name": "string_value",
        "pointer": "/string_value",
        "type": "string",
      },
      {
        "name": "read_count",
        "pointer": "/read_count",
        "type": "integer",
        "description": "Times values read"
      }
    ]
  }

After pmdajson is installed and the config file points to the directory
where the above JSON metadata and data files are, we can ask PCP for the
all the metrics under 'json.simple':

  # pminfo -f json.simple

  json.simple.read_count
      value 0

  json.simple.string_value
      value "testing, 1, 2, 3"

Note that the metadata.json file is read only once. If changes to a
metadata.json file are needed, the JSON pmda will need to be restarted
after the metadata.json changes are made.

METADATA FILE SYNTAX

Here's a description of metadata file syntax. First the "global" options:

- 'prefix' (optional): If present, the prefix string value names the
  base of the JSON source hierarchy. If not present, the base name of
  the directory name where the metadata file was found is used as the
  base of the JSON source hierarchy.

- 'data-path' (optional): By default, pmdajson assumes the associated
  JSON data for this metadata file will be named 'data.json' in the
  same directory. If this isn't the case, 'data-path' can be used to
  tell pmdajson where the JSON data file is located.

- 'data-exec' (optional): If this option is present, instead of
  getting the JSON data from a file, instead the data-exec string
  value names a command to be run to obtain the JSON data. If this
  JSON source directory came from the "directory_list" config file
  option, the command is run as user "nobody". If this JSON source
  directory came from the "trusted_directory_list" config file option,
  the command is run as user "root".

- 'metrics' (required): Each item in the 'metrics' array describes one
  metric. Each 'metrics' array item should contain the following
  fields:

  - 'name' (required): Metric name as a string.

  - 'type' (required): Metric type as a string. Possible values are
    'integer', 'double', 'string', or 'array'.

  - 'pointer' (required): JSON pointers (RFC 6901) that describes with
    metric location within the JSON data. Please refer to
    <https://tools.ietf.org/html/rfc6901> for more details on JSON
    pointer syntax.

  - 'description' (optional): Metric description as a string.

  - 'index' (required for arrays): Array index as a string. See the
    'ARRAY METADATA FILE SYNTAX' section for more details.

  - 'metrics' (required for arrays): List of array metrics. See the
    'ARRAY METADATA FILE SYNTAX' section for more details.

  - 'units' (optional): Metric unit description as a string. Values
    include the standard PCP unit names.

  - 'semantics' (optional): Metric semantic description as a string.
     Values include the standard PCP semantic types.


ARRAY METADATA FILE SYNTAX

Here's an example of a metadata file with an array to make how an
array works more clear. This example is from the net_xmit_json.stp
systemtap example file:

  {
    "prefix": "net_xmit",
    "metrics": [
      {
        "name": "net_xmit_data",
        "pointer": "/net_xmit_data",
        "type": "array",
        "description": "Network transmit data indexed by ethernet device",
        "index": "/__id",
        "metrics": [
          {
            "name": "xmit_count",
            "pointer": "/xmit_count",
            "type": "integer",
            "description": "number of packets for xmit device",
            "units": "count"
          },
          {
            "name": "xmit_latency",
            "pointer": "/xmit_latency",
            "type": "integer",
            "description": "sum of latency for xmit device"
          }
        ]
      }
    ]
  }

According to the above metadata file, there is one metric called
'net_xmit_data', which is an array. The array has 2 fields per array
entry, 'xmit_count' and 'xmit_latency'. The data looks like this:

  {
    "net_xmit_data": [
      {
        "__id": "eth0",
        "xmit_count": 352551,
        "xmit_latency": 55
      },
      {
        "__id": "fake0",
        "xmit_count": 0,
        "xmit_latency": 0
      },
      {
        "__id": "fake1",
        "xmit_count": 0,
        "xmit_latency": 0
      }
    ]
  }

In the above example data, the 'net_xmit_data' array has 3
entries. When pmdajson finds this data, it would look like this:

  # pminfo -f json
  
  json.net_xmit.net_xmit_data.xmit_latency
      inst [0 or "eth0"] value 55
      inst [1 or "fake0"] value 0
      inst [2 or "fake1"] value 0
  
  json.net_xmit.net_xmit_data.xmit_count
      inst [0 or "eth0"] value 352551
      inst [1 or "fake0"] value 0
      inst [2 or "fake1"] value 0
