path: root/src/pmdas/pmcd/help

#
# Copyright (c) 2013 Red Hat.
# Copyright (c) 2000,2004 Silicon Graphics, Inc.  All Rights Reserved.
# 
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License as published by the
# Free Software Foundation; either version 2 of the License, or (at your
# option) any later version.
# 
# This program is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
# or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
# for more details.
# 
# pmcd PMDA help file in the ASCII format
#
# lines beginning with a # are ignored
# lines beginning @ introduce a new entry of the form
#  @ metric_name oneline-text
#  help text goes
#  here over multiple lines
#  ...
#
# the metric_name is decoded against the default PMNS -- as a special case,
# a name of the form NNN.MM (for numeric NNN and MM) is interpreted as an
# instance domain identification, and the text describes the instance domain
#
# blank lines before the @ line are ignored
#

@ 2.1 Instance domain "pmloggers" from PMCD PMDA
This is the list of currently active pmlogger instances on the same
machine as this PMCD.  The instance names are the process ids of the
pmlogger instances.  The primary pmlogger has an extra instance with the
instance name "primary" and an instance id of zero (in addition to its
normal process id instance).

@ 2.2 pmcd control register Instance Domain
One instance per pmcd control register.

The internal instance identifiers are the numbers 0 to 15.
The external instance names are he ASCII equivalent of the internal
instance identifiers.

@ 2.3 PMDA Instance Domain
One instance per PMDA managed by PMCD.  The external and internal instance
identifiers are taken from the first two fields of the PMDA specification
in $PCP_PMCDCONF_PATH.

@ 2.4 pmie Instance Domain
One instance per running pmie process.  The internal and external instance
identifiers are the process ids of the pmie instances.

@ 2.5 buffer pool Instance Domain
The instances are as follows:

  1024  1024-byte PDU buffers managed by __pmFindPDUBuf, __pmPinPDUBuf
	and __pmUnpinPDUBuf
  2048  2-Kbyte PDU buffers managed by __pmFindPDUBuf, __pmPinPDUBuf
	and __pmUnpinPDUBuf
  4096  3-Kbyte or 4-Kbyte PDU buffers managed by __pmFindPDUBuf,
	__pmPinPDUBuf and __pmUnpinPDUBuf
  8192  5-Kbyte, 6-Kbyte, 7-Kbyte or 8-Kbyte PDU buffers managed by
	__pmFindPDUBuf, __pmPinPDUBuf and __pmUnpinPDUBuf
  8192+ PDU buffers larger that 8-Kbyte managed by __pmFindPDUBuf,
	__pmPinPDUBuf and __pmUnpinPDUBuf

@ pmcd.numagents Number of agents (PMDAs) currently connected to PMCD
The number of agents (PMDAs) currently connected to PMCD.  This may differ
from the number of agents configured in $PCP_PMCDCONF_PATH if agents have
terminated and/or been timed-out by PMCD.

@ pmcd.numclients Number of clients currently connected to PMCD
The number of connections open to client programs retrieving information
from PMCD.

@ pmcd.datasize Space allocated for PMCD and DSO agents' data segment (K)
This metric returns the amount of memory in kilobytes allocated for the
data segment of PMCD and any DSO agents (PMDAs) that it has loaded.

This is handy for tracing memory utilization (and leaks) in DSOs during
development.

@ pmcd.buf.alloc Allocated buffers in internal memory pools
This metric returns the number of allocated buffers for the various buffer
pools used by pmcd.

This is handy for tracing memory utilization (and leaks) in DSOs during
development.

@ pmcd.buf.free Free buffers in internal memory pools
This metric returns the number of free buffers for the various buffer
pools used by pmcd.

This is handy for tracing memory utilization (and leaks) in DSOs during
development.

@ pmcd.control.timeout Timeout interval for slow/hung agents (PMDAs)
PDU exchanges with agents (PMDAs) managed by PMCD are subject to timeouts
which detect and clean up slow or disfunctional agents.  This metric
returns the current timeout period in seconds being used for the agents.
If the value is zero, timeouts are not being used.  This corresponds to
the -t option described in the man page, pmcd(1).

It is possible to store a new timeout value into this metric.  Storing zero
will turn off timeouts.  Subsequent storing of a non-zero value will turn
on the timeouts again.

@ pmcd.control.debug Current value of PMCD debug flags
The current value of the PMCD debug flags.  This is a bit-wise OR of the
flags described in the output of pmdbg -l.  The PMCD-specific flags are:

    DBG_TRACE_APPL0       2048  Trace agent & client I/O and termination
    DBG_TRACE_APPL1       4096  Trace host access control
    DBG_TRACE_APPL2       8192  Trace config file scanner and parser

It is possible to store values into this metric.  Diagnostic output is
written to the PMCD log file (usually $PCP_LOG_DIR/pmcd/pmcd.log).

Setting this metric to -1 terminates PMCD.

@ pmcd.pdu_in.total Total PDUs received by PMCD
Running total of all BINARY mode PDUs received by the PMCD from clients
and agents.

@ pmcd.pdu_in.error ERROR PDUs received by PMCD
Running total of BINARY mode ERROR PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.result RESULT PDUs received by PMCD
Running total of BINARY mode RESULT PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.profile PROFILE PDUs received by PMCD
Running total of BINARY mode PROFILE PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.fetch FETCH PDUs received by PMCD
Running total of BINARY mode FETCH PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.desc_req DESC_REQ PDUs received by PMCD
Running total of BINARY mode DESC_REQ PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.desc DESC PDUs received by PMCD
Running total of BINARY mode DESC PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.instance_req INSTANCE_REQ PDUs received by PMCD
Running total of BINARY mode INSTANCE_REQ PDUs received by the PMCD
from clients and agents.

@ pmcd.pdu_in.instance INSTANCE PDUs received by PMCD
Running total of BINARY mode INSTANCE PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.text_req TEXT_REQ PDUs received by PMCD
Running total of BINARY mode TEXT_REQ PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.text TEXT PDUs received by PMCD
Running total of BINARY mode TEXT PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.control_req CONTROL_REQ PDUs received by PMCD
Running total of BINARY mode CONTROL_REQ PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.creds CREDS PDUs received by PMCD
Running total of BINARY mode CREDS PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.pmns_ids PMNS_IDS PDUs received by PMCD
Running total of BINARY mode PMNS_IDS PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.pmns_names PMNS_NAMES PDUs received by PMCD
Running total of BINARY mode PMNS_NAMES PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.pmns_child PMNS_CHILD PDUs received by PMCD
Running total of BINARY mode PMNS_CHILD PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.pmns_traverse PMNS_TRAVERSE PDUs received by PMCD
Running total of BINARY mode PMNS_TRAVERSE PDUs received by the PMCD from
clients and agents.

@ pmcd.pdu_in.auth AUTH PDUs received by PMCD
Running total of BINARY mode AUTH PDUs received by the PMCD from
clients and agents.  These PDUs are used for authentication.

@ pmcd.pdu_out.total Total PDUs sent by PMCD
Running total of all BINARY mode PDUs sent by the PMCD to clients and
agents.

@ pmcd.pdu_out.error ERROR PDUs sent by PMCD
Running total of BINARY mode ERROR PDUs sent by the PMCD to clients and
agents.

@ pmcd.pdu_out.result RESULT PDUs sent by PMCD
Running total of BINARY mode RESULT PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.profile PROFILE PDUs sent by PMCD
Running total of BINARY mode PROFILE PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.fetch FETCH PDUs sent by PMCD
Running total of BINARY mode FETCH PDUs sent by the PMCD to clients and
agents.

@ pmcd.pdu_out.desc_req DESC_REQ PDUs sent by PMCD
Running total of BINARY mode DESC_REQ PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.desc DESC PDUs sent by PMCD
Running total of BINARY mode DESC PDUs sent by the PMCD to clients and
agents.

@ pmcd.pdu_out.instance_req INSTANCE_REQ PDUs sent by PMCD
Running total of BINARY mode INSTANCE_REQ PDUs sent by the PMCD to
clients and agents.

@ pmcd.pdu_out.instance INSTANCE PDUs sent by PMCD
Running total of BINARY mode INSTANCE PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.text_req TEXT_REQ PDUs sent by PMCD
Running total of BINARY mode TEXT_REQ PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.text TEXT PDUs sent by PMCD
Running total of BINARY mode TEXT PDUs sent by the PMCD to clients and
agents.

@ pmcd.pdu_out.control_req CONTROL_REQ PDUs sent by PMCD
Running total of BINARY mode CONTROL_REQ PDUs sent by the PMCD to
clients and agents.

@ pmcd.pdu_out.creds CREDS PDUs sent by PMCD
Running total of BINARY mode CREDS PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.pmns_ids PMNS_IDS PDUs sent by PMCD
Running total of BINARY mode PMNS_IDS PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.pmns_names PMNS_NAMES PDUs sent by PMCD
Running total of BINARY mode PMNS_NAMES PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.pmns_child PMNS_CHILD PDUs sent by PMCD
Running total of BINARY mode PMNS_CHILD PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.pmns_traverse PMNS_TRAVERSE PDUs sent by PMCD
Running total of BINARY mode PMNS_TRAVERSE PDUs sent by the PMCD to clients
and agents.

@ pmcd.pdu_out.auth AUTH PDUs sent by PMCD
Running total of BINARY mode AUTH PDUs sent by the PMCD to clients
and agents.  These PDUs are used for authentication.

@ pmcd.pmlogger.host host where active pmlogger is running
The fully qualified domain name of the host on which a pmlogger
instance is running.

The instance names are process ids of the active pmloggers.  The
primary pmlogger has an extra instance with the instance name "primary"
and an instance id of zero (in addition to its normal process id
instance).

@ pmcd.pmlogger.port control port for active pmlogger
Each pmlogger instance has a port for receiving log control
information.  This metric is a list of the active pmlogger control
ports on the same machine as this PMCD (i.e. the host identified in the
corresponding pmcd.pmlogger.host metric).

The instance names are process ids of the active pmloggers.  The
primary pmlogger has an extra instance with the instance name "primary"
and an instance id of zero (in addition to its normal process id
instance).

@ pmcd.pmlogger.archive full pathname to archive basename for active pmlogger
The full pathname through the filesystem on the corresponding host
(pmcd.pmlogger.host) that is the base name for the archive log files.

The instance names are process ids of the active pmloggers.  The
primary pmlogger has an extra instance with the instance name "primary"
and an instance id of zero (in addition to its normal process id
instance).

@ pmcd.pmlogger.pmcd_host host from which active pmlogger is fetching metrics
The fully qualified domain name of the host from which a pmlogger
instance is fetching metrics to be archived.

The instance names are process ids of the active pmloggers.  The
primary pmlogger has an extra instance with the instance name "primary"
and an instance id of zero (in addition to its normal process id
instance).

@ pmcd.timezone local $TZ
Value for the $TZ environment variable where the PMCD is running.
Enables determination of "local" time for timestamps returned via
PMCD from a remote host.

@ pmcd.hostname local hostname
A reasonably unique identifier of the PMCD installation, for use
by pmlogger or other tools to identify the source principal of
the data (as distinct from identifying the connection/protocol
used to reach it).

@ pmcd.simabi Procedure call model and ABI version of this PMCD
SIM is the subprogram interface model (originally from the MIPS object
code formats), and ABI is the application binary interface.  Both
relate to the way the PMCD binary was compiled and linked.

Usually DSO PMDAs must be compiled and linked in the same way before
they can be used with PMCD.

On some platforms this metric is not available.

@ pmcd.version PMCD version

@ pmcd.control.register a vector of registers that may be set by users
A vector of 16 32-bit registers that are identified by the instance
identifiers 0 through 15.

The register contents are initially zero, but may be subsequently
modified to be an arbitrary value using pmStore(3) or pmstore(1).

The values are not used internally, but rather act as a repository into
which operational information might be stored, and then exported to
modify the behavior of client programs, e.g. inhibit pmie(1) rule
firing, or trigger a status indicator.  In this way,
pmcd.control.register acts like a primitive bulletin board.

Example use might be as follows
    register[0]	telephone no. of person assigned to current system problem
    register[1]	telephone no. of person assigned to current network problem
    register[2]	ORACLE database is down
    register[3]	backup in progress
    register[4]	shopping days to Christmas

@ pmcd.control.traceconn control PMCD connection event tracing
Set to 1 to enable PMCD event tracing for all connection-related
events for clients and PMDAs.

Set to 0 to disable PMCD connection event tracing.

@ pmcd.control.tracepdu control PMCD PDU event tracing
Set to 1 to enable PMCD event tracing for all PDUs sent and received
by PMCD.

Set to 0 to disable PMCD PDU event tracing.

@ pmcd.control.tracenobuf control buffering of PMCD event tracing
Set to 1 to enable unbuffered PMCD event tracing, where each event is
reported as it happens.

Set to 0 to enable buffering of PMCD event traces (this is the default),
and event traces will only be dumped or reported when an error occurs or
a value is stored into the PCP metric pmcd.control.dumptrace.

@ pmcd.control.tracebufs number of buffers for PMCD event tracing
Defaults to 20.  May be changed dynamically.

@ pmcd.control.dumptrace force dump of PMCD event tracing buffers
Storing any value into this metric causes the PMCD event trace buffers to
be dumped to PMCD's log file.

@ pmcd.control.sighup force PMCD reset via SIGHUP
Storing any value into this metric causes PMCD to be reset by sending
itself a SIGHUP signal.

On reset (either by storing into pmcd.control.sighup or by sending PMCD a
SIGHUP directly), PMCD will restart any failed PMDAs and reload the PMNS
if it has been changed.

@ pmcd.control.dumpconn force dump of PMCD client connections
Storing any value into this metric causes the details of the current PMCD
client connections to be dumped to PMCD's log file.

@ pmcd.agent.type PMDA type
From $PCP_PMCDCONF_PATH, this metric encodes the PMDA type as follows:
	(x << 1) | y
where "x" is the IPC type between PMCD and the PMDA, i.e. 0 for DSO, 1
for socket or 2 for pipe, and "y" is the message passing style, i.e.
0 for binary or 1 for ASCII.

@ pmcd.agent.status PMDA status
This metric encodes the current status of each PMDA.  The default value
is 0 if the PMDA is active.

Other values encode various degrees of PMDA difficulty in three bit fields
(bit 0 is the low-order bit) as follows:

bits 7..0
    1   the PMDA is connected, but not yet "ready" to accept requests
        from the PMDA
    2   the PMDA has exited of its own accord
    4   some error prevented the PMDA being started
    8   PMCD stopped communication with the PMDA due to a protocol or
        timeout error

bits 15..8
        the exit() status from the PMDA

bits 23..16
        the number of the signal that terminated the PMDA

@ pmcd.services running PCP services on the local host
A space-separated string representing all running PCP services with PID
files in $PCP_RUN_DIR (such as pmcd itself, pmproxy and a few others).

@ pmcd.openfds highest PMCD file descriptor
The highest file descriptor index used by PMCD for a Client or PMDA
connection.

@ pmcd.pmie.numrules number of rules being evaluated
The total number of rules being evaluated by each pmie process.

@ pmcd.pmie.eval.true count of pmie predicates evaluated to true
The predicate part of a pmie rule can be said to evaluate to either true,
false, or not known.  This metric is a cumulative count of the number of
rules which have evaluated to true for each pmie instance.

@ pmcd.pmie.eval.false count of pmie predicates evaluated to false
The predicate part of a pmie rule can be said to evaluate to either true,
false, or not known.  This metric is a cumulative count of the number of
rules which have evaluated to false for each pmie instance.

@ pmcd.pmie.eval.unknown count of pmie predicates not evaluated
The predicate part of a pmie rule can be said to evaluate to either true,
false, or not known.  This metric is a cumulative count of the number of
rules which have not been successfully evaluated.  This could be due to not
yet having sufficient values to evaluate the rule, or a metric fetch may
have been unsuccessful in retrieving current values for metrics required
for evaluation of the rule.

@ pmcd.pmie.eval.expected expected rate of rule evaluations
This is the expected rate of evaluation of pmie rules.  The value is
calculated once when pmie starts, and is the number of pmie rules divided
by the average time interval over which they are to be evaluated.

@ pmcd.pmie.eval.actual count of actual rule evaluations
A cumulative count of the pmie rules which have been evaluated.

This value is incremented once for each evaluation of each rule.

@ pmcd.pmie.actions count of rules evaluating to true
A cumulative count of the evaluated pmie rules which have evaluated to true.

This value is incremented once each time an action is executed.  This value
will always be less than or equal to pmcd.pmie.eval.true because predicates
which have evaluated to true may be suppressed in the action part of the
pmie rule, in which case this counter will not be incremented.

@ pmcd.pmie.configfile configuration file name
The full path in the filesystem to the configuration file containing the
rules being evaluated by each pmie instance.

If the configuration file was supplied on the standard input, then this
metric will have the value "<stdin>".  If multiple configuration files were
given to pmie, then the value of this metric will be the first configuration
file specified.

@ pmcd.pmie.pmcd_host default hostname for pmie instance
The default host from which pmie is fetching metrics.  This is either the
hostname given to pmie on the command line or the local host.  Note that this
does not consider host names specified in the pmie configuration file (these
are considered non-default and can be more than one per pmie instance).
All daemon pmie instances started through pmie_check(1) will have their
default host passed in on their command line.

@ pmcd.pmie.logfile filename of pmie instance event log
The file to which each instance of pmie is writting events.  No two pmie
instances can share the same log file.  If no logfile was specified when
pmie was started, this metrics has the value "<none>".  All daemon pmie
instances started through pmie_check(1) must have an associated log file.

@ pmcd.build build version for installed PCP package
Minor part of the PCP build version numbering.  For example on Linux
with RPM packaging, if the PCP RPM version is pcp-2.5.99-20070323 then
pmcd.build returns the string "20070323".

@ pmcd.client.whoami optional identification information for clients of pmcd
This metric is defined over an instance domain containing one entry
per active client of pmcd.  The instance number is a sequence number
for each client (restarts at 0 each time pmcd is restarted).  The value
of the metric by default is the IP address of the client.

Clients can optionally use pmStore to modify their own "whoami" string
to provide more useful information about the client.

@ pmcd.client.start_date date and time client connected to pmcd
The date and time in ctime(2) format on which the client connected
to pmcd.

@ pmcd.cputime.total CPU time used by pmcd and DSO PMDAs
Sum of user and system time since pmcd started.

@ pmcd.cputime.per_pdu_in average CPU time per PDU received by pmcd
When first requested it is the average since pmcd started, so
pmcd.cputime.total divided by pmcd.pdu_in.total.

Subsequent fetches by a PMAPI client will return the average CPU
time per PDU received by pmcd (for all clients) since the last time
the PMAPI client fetched this metric.

@ pmcd.feature.secure status of secure_sockets protocol feature in pmcd
A value of zero indicates no support, one indicates actively available
(including configuration and validity of the server side certificates).

@ pmcd.feature.compress status of protocol compression feature in pmcd
A value of zero indicates no support, one indicates actively available.

@ pmcd.feature.ipv6 status of Internet Protocol Version 6 support in pmcd
A value of zero indicates no support, one indicates actively available.

@ pmcd.feature.authentication status of per-user authentication support
A value of zero indicates no support, one indicates actively available.

@ pmcd.feature.creds_required status of required credentials support
A value of zero indicates no support, one indicates actively available.

@ pmcd.feature.unix_domain_sockets status of unix domain socket support
A value of zero indicates no support, one indicates actively available.

@ pmcd.feature.service_discovery status of service advertising and discovery
A value of zero indicates no support, one indicates actively available.