Provided by: pcp_5.3.7-1_amd64 bug

NAME

       pcp-htop - pcp-htop configuration file

DESCRIPTION

       pcp-htop  is  a  customizable  performance  metrics  reporting  tool.   It  has  a dynamic
       architecture, where a set of configuration files provide additional, optional  meters  and
       columns to extend the fixed set of display options provided by regular htop.

       These  configuration  files  can  be  provided  from  both  system-wide  locations  (first
       /etc/pcp/htop then /usr/share/pcp/htop) and  below  the  user's  home  directory  (usually
       ~/.config/htop).   Within  these  locations the meters and columns are scanned for dynamic
       Meter and Column specifications.

       Meters are displayed in the top part of the pcp-htop window, and columns are displayed  in
       the  lower  part.  Meters tend to display system-wide metrics, and Columns display metrics
       about individual processes.

       The formats are similar but have slightly different requirements.  Both formats follow the
       common  ini-style.  Blank  lines  are  ignored.  Lines starting with the "#" character are
       treated as comments.

METERS

       The following is an example configuration for a new Redis meter:

            [redisclient]
            caption = Redis clients
            type = bar
            blocked.metric = redis.blocked_clients
            blocked.color = blue
            blocked.label = blk
            clients.metric = redis.connected_clients
            clients.color = green
            clients.label = conn

       A configuration file can contain multiple meter definitions.  Each definition begins  with
       a identifying name enclosed by square brackets - redisclient in this example.  The name is
       used internally within pcp-htop  and  must  be  unique,  must  begin  with  an  alphabetic
       character,  and  may  subsequently  only contain alphanumeric characters or the underscore
       character.  No whitespace or other characters are allowed.

       There are several parameters that define the way the meter will be displayed to the user.

       caption
            This value is displayed on the Setup screen once the  meter  has  been  selected.   A
            truncated  version of the caption will also be displayed (followed by a colon) on the
            primary display while the meter is updating.

       description
            This can be used to provide more detail during the meter  selection  process  on  the
            Setup  screen,  and  if present it is displayed in the "Available Meters" column.  If
            not present, the caption will be used for this.  If neither is present, the  internal
            (mandatory) name will be used.

       type This  setting  allows a preferred default meter type to be specified.  The associated
            value must be one of bar, text, graph, or led.  If no value is provided for a dynamic
            meter, the default value of text will be used.

       maximum
            A  numeric  value can also be set to size the meter, such that values (e.g. for a bar
            type meter display) will be scaled within range zero to maximum.

       The remaining definition syntax describes the individual metric(s) which will be  used  to
       animate  the  meter.   One  or more metrics must be specified for each meter and there are
       several properties associated with each.  Once again, these metrics  must  be  named  (the
       same  rules  described  above  for  meters apply here) and the following properties can be
       configured:

       name.metric
            This is the only mandatory field and associates a PCP metric with the meter.   Values
            sampled  for  each  metric  at  runtime provide the animation visible in the pcp-htop
            display.  The metric specification can be either a  PCP  metric  name  as  listed  by
            pminfo(1)   or  a  "derived"  metric  expression.   The  format  for  derived  metric
            expressions is described on the pmRegisterDerived(3) manual page.

       name.color
            Setting color to be used when rendering metric  values.   Possible  values  are  red,
            green, blue, cyan, magenta, yellow, gray, darkgray or white.

       name.label
            An  optional, short label to display before the metric value.  The ":" character will
            be appended to the label before the metric value part of the display.

       name.suffix
            An optional, short suffix to display  after  the  metric  value.   Commonly  used  to
            indicate values as a percentage using a "%" suffix value and to provide the base unit
            of measurement.  Note that since PCP maintains units for metrics, for  those  metrics
            that  have  dimension in "space" (bytes, kilobytes, megabytes, etc), a suffix will be
            automatically appended.

COLUMNS

       The following is an example configuration for a new column showing open  file  descriptors
       for each process:

            [openfds]
            heading = FDS
            caption = FDCOUNT
            description = Open file descriptors
            metric = proc.fd.count
            width = 3

       A configuration file can contain multiple column definitions.  Each definition begins with
       a identifying name enclosed by square brackets - openfds in this  example,  and  the  same
       rules apply as described above for meter names.

       Each column must specify a metric.  Optional parameters can also be set.

       metric
            As  with  meters,  the  metric  value  must  be either a PCP metric name as listed by
            pminfo(1) or a derived metric.  The metric must  have  an  instance  domain  (set  of
            values)  and  that instance domain must map to the set of processes with the instance
            identifier being PIDs (process identifiers).  Typically this will be metrics from the
            proc  or hotproc namespace (pmdaproc(1)), but metrics from other domains (pmdabcc(1),
            pmdabpf(1), etc) that have per-process values are equally applicable.

       width
            Column width to use when displaying values for the metric.  A negative value  can  be
            used  to specify left alignment.  An upper column limit of 28 characters is enforced.
            The default column width is 5 characters.

       heading
            The short title that will be displayed at the head of the column - usually  a  short,
            cryptic, all uppercase string.

       caption
            A  short  identifying  word  presented  to  users  on the Setup screen under both the
            Available and Active Columns lists.

       description
            Text that assists users to understand the meaning of this column  when  it  is  being
            presented via the Setup screen in the Available Columns list.

SEE ALSO

       pcp-htop(1),    pminfo(1),    pmcd(1),    pmdaproc(1),    pmdabcc(1),    pmdabpf(1)    and
       pmRegisterDerived(3).

AUTHORS

       htop was originally developed by Hisham  Muhammad.   Nowadays  it  is  maintained  by  the
       community at <htop@groups.io>.

       pcp-htop is maintained as a collaboration between the <htop@groups.io> and <pcp@groups.io>
       communities, and forms part of the Performance Co-Pilot suite of tools.