TrxShell [ mangaberri.com ]

Name	Size	Permission
Install	888 B	-rwxr-xr-x
README	6.49 KB	-rw-r--r--
Remove	682 B	-rwxr-xr-x
generate_ceph_metadata	8.84 KB	-rwxr-xr-x
pmdajson.python	53.62 KB	-rwxr-xr-x

Code Editor : README

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 source
directories:

JSON data sources listed for the directory_list option are not trusted,
meaning that if external commands to generate the needed JSON data are
used, these commands are run as user nobody.

JSON data sources listed for the trusted_directory_list option are
trusted, meaning that if external commands to generate the needed JSON
data are used, these commands are run as user root.

Example config.json:

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

Note that the config.json config file is read once when the JSON PMDA
starts. Every time metric values are requested, the directories listed
in the 'directory_list' and 'trusted_directory_list' config file options
are traversed, looking for updated JSON data sources (described below).

JSON DATA SOURCES

There are two sets of information needed for a particular JSON source: a
JSON metadata file and the associated JSON data (read either from a file
or from output of an external command). 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 PMNS
(see PMNS(5)).

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 all
the metrics under PMNS '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, pmdajson needs to be restarted after
the metadata.json changes have been 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.

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

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

- 'units' (optional): Metric unit description as a string. Values
    include the standard PCP unit names like 'sec' or 'bytes', see
    pmLookupDesc(3).

- 'semantics' (optional): Metric semantic description as a string.
     Values include the standard PCP semantic types which are
    'counter', 'instant', 'discrete', see pmLookupDesc(3).

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

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

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

ARRAY METADATA FILE SYNTAX

Below is an example of a metadata file with an array which are needed
when using non-leaf nodes for the metrics in PMNS:

{
    "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",
            "units": "count",
            "semantics": "counter",
            "description": "Number of packets for xmit device"
          },
          {
            "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 two 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": "eth1",
        "xmit_count": 0,
        "xmit_latency": 0
      },
      {
        "__id": "eth2",
        "xmit_count": 0,
        "xmit_latency": 0
      }
    ]
  }

In the above example data, the 'net_xmit_data' array has three entries
which will map to three metric instances.

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 "eth1"] value 0
      inst [2 or "eth2"] value 0
  
  json.net_xmit.net_xmit_data.xmit_count
      inst [0 or "eth0"] value 352551
      inst [1 or "eth1"] value 0
      inst [2 or "eth2"] value 0

${this.title}

Code Editor : README