---
name: "pmtrace"
section: "1"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmtrace"
---

# pmtrace(1)

command line performance instrumentation

## NAME

**pmtrace** - command line performance instrumentation

## SYNOPSIS

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

## DESCRIPTION

**pmtrace** provides a simple command line interface to the trace Performance Metrics Domain Agent (PMDA) and the associated *pcp\_trace* library.

The default **pmtrace** behavior is to provide point trace data to the trace PMDA, using the *tag* argument as the identifying name associated with each trace point. The *tag* then becomes an instance identifier within the set of trace.point metrics.

## OPTIONS

The available command line options are:

- **-c** *value*

  Allow an arbitrary counter *value* to be exported through the trace.count metrics.

- **-e** *command*

  Allow an arbitrary *command* to be executed. This *command* will be measured as a transaction since it has well defined start and end points. The information is made available through the trace.transact metrics.

- **-h** *host*

  Sent the trace data to the trace PMDA running on *host*, rather than the localhost. This overrides use of the environment variable **PCP\_TRACE\_HOST**.

- **-q**

  Suppress messages from a successful trace, so that **pmtrace** runs quietly.

- **-S** *state*

  Enable internal debugging and tracing. The value of *state* is a bit-wise combination of debug flags as defined in [**pmtracestate**(3)](/pmtracestate/3.md), and may be specified using the decimal or hexadecimal syntax prescribed by [**strtol**(3)](/strtol/3.md).

- **-v** *value*

  Allow an arbitrary floating point *value* to be exported through the trace.observe metrics.

- **-?**

  Display usage message and exit.

## DIAGNOSTICS

All are generated on standard error and are intended to be self-explanatory.

The **pmtrace** exit status is always zero except when the **-e** option is in use, in which case the exit status of *command* is returned.

## FILES

- **$PCP\_DEMOS\_DIR/trace/pmtrace.c**

  source code for **pmtrace**

## ENVIRONMENT

Since **pmtrace** uses the *libpcp\_trace* library routines, the environment variables **PCP\_TRACE\_HOST**, **PCP\_TRACE\_PORT**, and **PCP\_TRACE\_TIMEOUT** are all honored. Refer to [**pmdatrace**(3)](/pmdatrace/3.md) for a detailed description of the semantics of each.

## 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)](/pcp.conf/5.md).

## SEE ALSO

[**pmcd**(1)](/pmcd/1.md), [**pmdatrace**(1)](/pmdatrace/1.md), [**pmprobe**(1)](/pmprobe/1.md), [**PMAPI**(3)](/PMAPI/3.md) and [**pmdatrace**(3)](/pmdatrace/3.md).