'\"macro stdmacro
.\"
.\" Copyright (c) 2015-2018 Red Hat.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMDAJSON 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdajson\f1 \- JSON PMDA
.SH DESCRIPTION
\fBpmdajson\fP is a Performance Metrics Domain Agent (PMDA) which exports
metrics from arbitrary sources generating JavaScript Object Notation
(JSON) syntax.
.PP
At least one pair of JSON inputs are required for \fBpmdajson\fP 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.
.PP
The overall JSON format description is at
.BR http://www.json.org/ .
.SH JSON DATA SOURCES
\fBpmdajson\fP reads a mandatory JSON configuration file
.IP
.PD 0
.RS +4
.IP \(bu 2
.I \f(CR$PCP_PMDAS_DIR\fP/json/config.json
.RE
.PD
.PP
This file can contain the following PMDA options using the JSON syntax:
.IP
.PD 0
.RS +4
.IP \(bu 2
directory_list
.IP \(bu
trusted_directory_list
.RE
.PD
.PP
\fBpmdajson\fP searches the directories listed for these options
looking for files named \fImetadata.json\fP and (by default)
\fIdata.json\fP.
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.
.PP
Each of these found JSON file/command pairs form a \fIJSON data source\fP.
.PP
For example, let us assume the following simple JSON data file that
contains values for two metrics, one of type string and one numeric:
.PP
.nf
.fam C
  {
    "string_value": "testing, 1, 2, 3",
    "read_count": 0
  }
.fam P
.fi
.PP
For these metrics the metadata file needed by \fBpmdajson\fP would be:
.PP
.nf
.fam C
  {
    "metrics": [
      {
        "name": "string_value",
        "pointer": "/string_value",
        "type": "string"
      },
      {
        "name": "read_count",
        "pointer": "/read_count",
        "type": "integer",
        "description": "Times values read"
      }
    ]
  }
.fam P
.fi
.PP
For further details on the JSON metadata format and options,
see the README file included as part of \fBpmdajson\fP installation.
.SH SECURITY MODEL
JSON data sources listed for the \fIdirectory_list\fP option are not
trusted, meaning that if external commands to generate the needed
JSON data are used, these commands are run as user \fBnobody\fP.
.PP
JSON data sources listed for the \fItrusted_directory_list\fP option
are trusted, meaning that if external commands to generate the needed
JSON data are used, these commands are run as user \fBroot\fP.
.PP
For further details on security and description on running external
commands, see the README file included as part of \fBpmdajson\fP
installation.
.SH INSTALLATION
Install the JSON PMDA by using the Install script as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/json
# ./Install
.fi
.ft P
.RE
.sp 1
To uninstall, do the following as root:
.sp 1
.RS +4
.ft B
.nf
# cd $PCP_PMDAS_DIR/json
# ./Remove
.fi
.ft P
.RE
.sp 1
\fBpmdajson\fP is launched by \fBpmcd\fP(1) and should never be
executed directly.
The Install and Remove scripts notify \fBpmcd\fP(1) when the
agent is installed or removed.
.SH FILES
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/json/README
additional documentation for \fBpmdajson\fP used JSON files
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/json/config.json
configuration file for the \fBpmdajson\fP agent
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/json/Install
installation script for the \fBpmdajson\fP agent
.TP
.I \f(CR$PCP_PMDAS_DIR\fP/json/Remove
undo installation script for the \fBpmdajson\fP agent
.TP
.I \f(CR$PCP_LOG_DIR\fP/pmcd/json.log
default log file for messages from the \fBpmdajson\fP agent
.SH PCP ENVIRONMENT
Environment variables with the prefix \fBPCP_\fP are used to parameterize
the file and directory names used by PCP.
On each installation, the
file \fI/etc/pcp.conf\fP contains the local values for these variables.
The \fB$PCP_CONF\fP variable may be used to specify an alternative
configuration file, as described in \fBpcp.conf\fP(5).
.SH SEE ALSO
.BR PCPIntro (1),
.BR pmcd (1)
and
.BR pminfo (1).