PMDAJSON(1)

✨ NAME ✨

okay so bestie, this is pmdajson — the JSON PMDA 💅 (that's a Performance Metrics Domain Agent, iykyk). It's the little icon that exports metrics from literally any source that spits out JavaScript Object Notation (JSON). No cap. 🦋

---

🌸 DESCRIPTION 🌸

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

Here's the tea, bestie: for pmdajson to actually feed metrics to PCP clients, you need at least one pair of JSON inputs. Not one. A pair. 🫶

1. one that describes the metric metadata
2. one that holds the actual metric values data

The metadata gets read once from a file at PMDA startup. The data, though? The data gets read every single time a PCP client asks for metric values. Every. Time. 😭

That data can come from either a JSON file or an external command generating JSON output — your choice, main character.

And because we're extra: you can use more than one pair of JSON inputs to support an arbitrary number of metric sources in different configured directories. The more the merrier fr fr 💖

The overall JSON format description lives at http://www.json.org/ — go peek if you want the lore.

---

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

🍓 Example time 🍓

Let's 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 🔒

okay this part is important so listen up bestie, no scrolling past 🙈

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

⚠️ running stuff as root is the vibe check of this whole page — make sure you actually trust it before you trust-list it, fr.

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. It's giving backstage pass only — pmcd(1) handles the intro. 💅

The Install and Remove scripts notify pmcd(1) when the agent is installed or removed. Teamwork makes the dream work ✨

---

📁 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). Obsessed with a configurable config, honestly.

---

👀 SEE ALSO 👀

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

---

Performance Co-Pilot • PCP • PMDAJSON(1) — that's the source/version and date energy right there, bestie. mwah, go export some metrics, you ate 💖✨🎀🦋