# pmdajson

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


* * *