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).