PMTRACE(1)

✨ PMTRACE(1) — bestie edition ✨

okay so welcome to pmtrace from the General Commands Manual section, and literally this is the moment your command line gets ✨instrumented✨. no cap.

---

🎀 NAME 🎀

pmtrace — command line performance instrumentation. yes, performance instrumentation, and yes it's giving main character energy for your metrics.

---

🌸 SYNOPSIS 🌸

pmtrace [-q?]  [-c value | -e command | -v value] [-h host] [-S state]
tag

---

🦋 DESCRIPTION 🦋

So pmtrace is basically a super simple command line interface to the trace Performance Metrics Domain Agent (PMDA) plus the whole pcp_trace library that comes with it. it's the group chat between your terminal and the trace PMDA, fr fr.

By default — like, if you don't tell it anything else — pmtrace does the point trace data thing: it hands point trace data over to the trace PMDA, and it uses the tag argument as the identifying name that goes with each trace point. that tag then becomes an instance identifier inside the set of trace.point metrics. iconic behavior honestly. 👑

---

💅 OPTIONS 💅

here's the whole menu, bestie, and we are NOT skipping a single one:

• -c value — lets you export an arbitrary counter value out through the trace.count metrics.
• -e command — lets you run an arbitrary command. this one gets measured as a transaction because it has well defined start and end points (slay, it knows where it begins and where it ends 😌). the info ends up available through the trace.transact metrics.
• -h host — sends the trace data to the trace PMDA running on host, instead of on localhost. heads up: this one overrides your use of the PCP_TRACE_HOST environment variable. 💀
• -q — suppresses messages from a successful trace, so pmtrace just runs quietly. shhh. 🙈
• -S state — enables internal debugging and tracing. the value of state is a bit-wise combination of debug flags, exactly as defined in pmtracestate(3), and you can write it with the decimal or hexadecimal syntax that strtol(3) prescribes.
• -v value — lets you export an arbitrary floating point value out through the trace.observe metrics.
• -? — display the usage message and exit. bye ✌️

---

😭 DIAGNOSTICS 😭

All of them get generated on standard error, and they're all meant to be self-explanatory (as they should be, honestly).

The pmtrace exit status is always zero — except when the -e option is in use, and in that case the exit status of command gets returned instead. so like, if you're using -e, the exit status is literally not your own anymore. it's command's. periodt.

---

🍓 FILES 🍓

• $PCP_DEMOS_DIR/trace/pmtrace.c — source code for pmtrace

---

🧚 ENVIRONMENT 🧚

Since pmtrace uses the libpcp_trace library routines, these environment variables are all honored: PCP_TRACE_HOST, PCP_TRACE_PORT, and PCP_TRACE_TIMEOUT. if you wanna know the detailed semantics of each one, go read pmdatrace(3) — it explains all of it. 🫶

---

🌈 PCP ENVIRONMENT 🌈

Environment variables with the prefix PCP_ are the ones used to parameterize the file and directory names that PCP uses. on each installation, the file /etc/pcp.conf contains the local values for these variables. and the $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5).

---

⭐ SEE ALSO ⭐

pmcd(1), pmdatrace(1), pmprobe(1), PMAPI(3) and pmdatrace(3).

---

okay bestie that's the whole page, go forth and trace 💖 and one lil sign-off: this whole thing is Performance Co-Pilot, from PCP, and it's the PMTRACE(1) page — mwah, hope it ate 🌸✨💅