NAME

       pmdajson - JSON PMDA

DESCRIPTION

       pmdajson  is  a  Performance  Metrics  Domain  Agent  (PMDA) which exports metrics from arbitrary sources
       generating JavaScript Object Notation (JSON) syntax.

       At least one pair of JSON inputs are required for pmdajson  to  provide  metrics  for  PCP  clients;  one
       describing  metric  metadata and one containing metric values data.  Metadata is read once from a file at
       PMDA startup while the data is read every time a request for metric values is made by a PCP client.   The
       data  is  read either from a JSON file or an external command generating JSON output.  More than one pair
       of JSON inputs can be used to  support  arbitrary  number  of  metric  sources  in  different  configured
       directories.

       The overall JSON format description is at http://www.json.org/.

JSON DATA SOURCES

       pmdajson reads a mandatory JSON configuration file

           • $PCP_PMDAS_DIR/json/config.json

       This file can contain the following PMDA options using the JSON syntax:

           • directory_list
           • trusted_directory_list

       pmdajson  searches the directories listed for these options looking for files named metadata.json and (by
       default) data.json.  The JSON metadata files describe the metric names, types, and other details  of  the
       associated  JSON  metric  data.   The  JSON  data  file name is configurable, and can also be an external
       command instead of a periodically updated (by external tools) data file.

       Each of these found JSON file/command pairs form a JSON data source.

       For example, let us assume the following simple JSON data file that contains values for two metrics,  one
       of type string and one numeric:

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

       For these metrics the metadata file needed by pmdajson would be:

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

       For  further  details  on  the  JSON metadata format and options, see the README file included as part of
       pmdajson installation.

SECURITY MODEL

       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.

       For further details on security and description  on  running  external  commands,  see  the  README  file
       included as part of pmdajson installation.

INSTALLATION

       Install the JSON PMDA by using the Install script as root:

           # cd $PCP_PMDAS_DIR/json
           # ./Install

       To uninstall, do the following as root:

           # cd $PCP_PMDAS_DIR/json
           # ./Remove

       pmdajson  is  launched  by pmcd(1) and should never be executed directly.  The Install and Remove scripts
       notify pmcd(1) when the agent is installed or removed.

FILES

       $PCP_PMDAS_DIR/json/README
              additional documentation for pmdajson used JSON files

       $PCP_PMDAS_DIR/json/config.json
              configuration file for the pmdajson agent

       $PCP_PMDAS_DIR/json/Install
              installation script for the pmdajson agent

       $PCP_PMDAS_DIR/json/Remove
              undo installation script for the pmdajson agent

       $PCP_LOG_DIR/pmcd/json.log
              default log file for messages from the pmdajson agent

PCP ENVIRONMENT

       Environment variables with the prefix PCP_ are used to parameterize the file and directory names used  by
       PCP.   On  each  installation, the file /etc/pcp.conf contains the local values for these variables.  The
       $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

SEE ALSO

       PCPIntro(1), pmcd(1) and pminfo(1).