PMDATRACE(1)

💖 PMDATRACE(1) 💖

okay bestie, welcome to the General Commands Manual section, we're talking pmdatrace today and honestly? it's iconic. grab a strawberry drink, this one's a whole vibe 🍓✨

---

🌸 NAME 🌸

pmdatrace — application-level transaction performance metrics domain agent

like... it's a PMDA. it does transactions. it's that girl. 💅

---

🦋 SYNOPSIS 🦋

$PCP_PMDAS_DIR/trace/pmdatrace [-D debug] [-d domain] [-l logfile] [-A
access] [-I port] [-M username] [-N buckets] [-T period] [-U units]

---

✨ DESCRIPTION ✨

So pmdatrace is a Performance Metrics Domain Agent (PMDA), and what it does is export transaction performance metrics from application processes that use the pcp_trace library described over in pmdatrace(3). no cap, that's literally its whole job and it ate. 👑

Here's the lowdown on the command line options, one by one:

• -d — bestie, listen. It is absolutely crucial that the performance metrics domain number you put here is unique and consistent. Like, this is not a drill. domain should be different for every single PMDA on one host, and the same domain number should be used for the same PMDA on all hosts. consistency is the moment, periodt.
• -l — where the log file lives. by default, a log file named trace.log gets written in the current directory of pmcd(1) when pmdatrace is started, which is to say $PCP_LOG_DIR/pmcd. If the log file can't be created or isn't writable, the output goes to the standard error instead. 🙈
• -A — host-based access control for pmdatrace. access has to be either an allow or deny specification, using either allow:hostspec:maxconns or disallow:hostspec, where allow and disallow are keywords, hostspec is a host specification that conforms to the format used by both pmcd(1) and pmlogger(1), and maxconns is the max number of connections allowed from a given hostspec. Using a maximum connections of zero means unlimited connections for the accompanying hostspec. unlimited! she's generous 💖
• -I — talk to pcp_trace clients via the given Internet port. you can also just set $PCP_TRACE_PORT in the environment to some valid port number instead (and heads up, using the -I option overrides that). The default port number is 4323. 🔥
• -T — period defines the aggregation period used to compute the recent averages and extrema. It's specified as a time interval using the syntax described in PCPIntro(1) for the common -t PCP argument, e.g. 30 seconds or 1 min. The default is 60 seconds.
• -M — the user account to run the agent under. The default is the unprivileged "pcp" account in current versions of PCP, but in older versions the superuser account ("root") was used by default. glow-up fr fr 🌈
• -N — internally, the aggregation period gets divided into bucket divisions, and the rolling average is recomputed every period/bucket seconds. for example, the defaults correspond to -T 60 and -N 12, which means the average is recomputed every five seconds for a period covering the prior 60 seconds. math girlies rise 🧚
• -U — this one lets you configure the dimension and scale associated with the observation value metric. units is a comma-separated string of six integer values, and those are the space dimension, time dimension, count dimension, space scale, time scale, and count scale — respectively, in that exact order. The default dimension and scale is none, which is equivalent to passing 0,0,0,0,0,0 as the argument to -U. The units associated with a metric are most easily viewed using the -d (metric description) option to pminfo(1). and the Install script described below steps through this option quite explicitly, so it is recommended that the Install script be used for building up the units specification. let the script cook 👩‍🍳

Essentially — and this is the summary bestie — the exported metrics provide statistics on the time for completion of each transaction, plus an average count of transactions completed and watch points passed over a given time period. cute, useful, efficient. we love her. 🫶

---

💜 INSTALLATION 💜

In order for a host to export the names, help text and values for the Trace performance metrics, do the following as root:

# cd $PCP_PMDAS_DIR/trace
# ./Install

If you want to undo the installation (noooo why would you 😭), do the following as root:

# cd $PCP_PMDAS_DIR/trace
# ./Remove

pmdatrace 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. so like, let the scripts handle the admin, you just vibe. 💅

---

🎀 FILES 🎀

• $PCP_PMCDCONF_PATH — command line options used to launch pmdatrace
• $PCP_PMDAS_DIR/trace/help — default help text file for the trace metrics
• $PCP_DEMOS_DIR/trace/* — example programs which use the pcp_trace library
• $PCP_PMDAS_DIR/trace/Install — installation script for the pmdatrace agent
• $PCP_PMDAS_DIR/trace/Remove — undo installation script for pmdatrace
• $PCP_LOG_DIR/pmcd/trace.log — default log file for error messages and other information from pmdatrace

---

🌈 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). config files are the blueprint, and we respect the blueprint. ✨

---

💀 DEBUGGING OPTIONS 💀

The -D or --debug option enables the output of additional diagnostics on stderr to help triage problems, although ngl the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users. debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning. iykyk. 🔍

Debugging options specific to pmdatrace are as follows:

• appl0 — authentication parsing, client changes, IPC, metric data and metadata refreshes
• appl1 — raw data for rate metrics

---

👑 SEE ALSO 👑

PCPIntro(1), pmcd(1), pmtrace(1), PMAPI(3) and pmdatrace(3).

---

and that's the whole page bestie, you're basically a pmdatrace expert now ⭐ this was the Performance Co-Pilot edition from PCP, and yeah, it's a PMDATRACE(1) situation. go forth and export those transaction metrics, you absolute main character 🦋💖🌸