Provided by: libpcp-pmda-perl_3.10.8build1_amd64 bug

NAME

       PCP::PMDA - Perl extension for Performance Metrics Domain Agents

SYNOPSIS

         use PCP::PMDA;

         $pmda = PCP::PMDA->new('myname', $MYDOMAIN);

         $pmda->connect_pmcd;

         $pmda->add_metric($pmid, $type, $indom, $sem, $units, 'name', '', '');
         $pmda->add_indom($indom, [0 => 'white', 1 => 'black', ...], '', '');

         $pmda->set_fetch(\&fetch_method);
         $pmda->set_refresh(\&refresh_method);
         $pmda->set_instance(\&instance_method);
         $pmda->set_fetch_callback(\&fetch_callback_method);
         $pmda->set_store_callback(\&store_callback_method);

         $pmda->set_user('pcp');

         $pmda->run;

DESCRIPTION

       The PCP::PMDA Perl module contains the language bindings for building Performance Metric
       Domain Agents (PMDAs) using Perl.  Each PMDA exports performance data for one specific
       domain, for example the operating system kernel, Cisco routers, a database, an
       application, etc.

METHODS

       PCP::PMDA->new(name, domain)
           PCP::PMDA class constructor.  name is a string that becomes the name of the PMDA for
           messages and default prefix for the names of external files used by the PMDA.  domain
           is an integer domain number for the PMDA, usually from the register of domain numbers
           found in $PCP_VAR_DIR/pmns/stdpmid.

       $pmda->run()
           Once all local setup is complete (i.e. instance domains and metrics are registered,
           callbacks registered - as discussed below) the PMDA must connect to pmcd(1) to
           complete its initialisation and begin answering client requests for its metrics.  This
           is the role performed by run, and upon invoking it all interaction within the PMDA is
           done via callback routines (that is to say, under normal cicrumstances, the run
           routine does not return).

           The behaviour of the run method is different in the presence of either the
           PCP_PERL_PMNS or PCP_PERL_DOMAIN environment variables.  These can be used to generate
           the namespace or domain number files, which are used as part of the PMDA installation
           process.

       $pmda->connect_pmcd()
           Allows the PMDA to set up the IPC channel to pmcd(1) and complete the credentials
           handshake with pmcd(1).  If connect_pmcd is not explicitly called the setup and
           handshake will be done when the run method is called.

           The advantage of explicitly calling connect_pmcd early in the life of the PMDA is that
           this reduces the risk of a fatal timeout during the credentials handshake, which may
           be an issue if the PMDA has considerable work to do, e.g. determining which metrics
           and instance domains are available, before calling run.

       $pmda->add_indom(indom, insts, help, longhelp)
           Define a new instance domain.  The instance domain identifier is indom, which is an
           integer and unique across all instance domains for single PMDA.

           The instances of the instance domain are defined by insts which can be specified as
           either a list or a hash.

           In list form, the contents of the list must provide consecutive pairs of identifier (a
           integer, unique across all instances in the instance domain) and external instance
           name (a string, must by unique up to the first space, if any, across all instances in
           the instance domain).  For example:

            @colours = [0 => 'red', 1 => 'green', 2 => 'blue'];

           In hash form, the external instance identifier (string) is used as the hash key.  An
           arbitrary value can be stored along with the key (this value is often used as a
           convenient place to hold the latest value for each metric instance, for example).

            %timeslices = ('sec' => 42, 'min' => \&min_func, 'hour' => '0');

           The help and longhelp strings are interpreted as the one-line and expanded help text
           to be used for this instance domain as further described in pmLookupInDomText(3).

           Refer also to the replace_indom() discussion below for further details about
           manipulating instance domains.

       $pmda->add_metric(pmid, type, indom, sem, units, name, help, longhelp)
           Define a new metric identified by the PMID pmid and the full metric name name.

           The metric's metadata is defined by type, indom, sem and units and these parameters
           are used to set up the pmDesc structure as described in pmLookupDesc(3).

           The help and longhelp strings are interpreted as the one-line and expanded help text
           to be used for the metric as further described in pmLookupText(3).

       $pmda->replace_indom(index, insts)
           Whenever an instance domain identified by index, previously registered using
           add_indom(), changes in any way, this change must be reflected by replacing the
           existing mapping with a new one (insts).

           The replacement mapping must be a hash if the instance domain was registered initially
           with add_indom() as a hash, otherwise it must be a list.

           Refer to the earlier add_indom() discussion concerning these two different types of
           instance domains definitions.

       $pmda->add_pipe(command, callback, data)
           Allow data to be injected into the PMDA using a pipe(2).

           The given command is run early in the life of the PMDA, and a pipe is formed between
           the PMDA and the command.  Line-oriented output is assumed (else truncation will
           occur), and on receipt of each line of text on the pipe, the callback function will be
           called.

           The optional data parameter can be used to specify extra data to pass into the
           callback routine.

       $pmda->add_sock(hostname, port, callback, data)
           Create a socket(2) connection to the hostname, port pair.  Whenever data arrives (as
           above, a line-oriented protocol is best) the callback function will be called.

           The optional data parameter can be used to specify extra data to pass into the
           callback routine.

           An opaque integer-sized identifier for the socket will be returned, which can later be
           used in calls to put_sock() as discussed below.

       $pmda->put_sock(id, output)
           Write an output string to the socket identified by id, which must refer to a socket
           previously registered using add_sock().

       $pmda->add_tail(filename, callback, data)
           Monitor the given filename for the arrival of newly appended information.  Line-
           oriented input is assumed (else truncation will occur), and on receipt of each line of
           text on the pipe, the callback function will be called.

           The optional data parameter can be used to specify extra data to pass into the
           callback routine.

           This interface deals with the issue of the file being renamed (such as on daily log
           file rotation), and will attempt to automatically re-route information from the new
           log file if this occurs.

       $pmda->add_timer(timeout, callback, data)
           Registers a timer with the PMDA, such that on expiry of a timeout a callback routine
           will be called.  This is a repeating timer.

           The optional data parameter can be used to specify extra data to pass into the
           callback routine.

       $pmda->err(message)
           Report a timestamped error message into the PMDA log file.

       $pmda->error(message)
           Report a timestamped error message into the PMDA log file.

       $pmda->log(message)
           Report a timestamped informational message into the PMDA log file.

       $pmda->set_fetch_callback(cb_function)
           Register a callback function akin to pmdaSetFetchCallBack(3).

       $pmda->set_fetch(function)
           Register a fetch function, as used by pmdaInit(3).

       $pmda->set_instance(function)
           Register an instance function, as used by pmdaInit(3).

       $pmda->set_refresh(function)
           Register a refresh function, which will be called once per metric cluster, during the
           fetch operation.  Only clusters being requested during this fetch will be refreshed,
           allowing selective metric value updates within the PMDA.

       $pmda->set_store_callback(cb_function)
           Register an store function, used indirectly by pmdaInit(3).  The cb_function is called
           once for each metric/instance pair into which a pmStore(3) is performed.

       $pmda->set_inet_socket(port)
           Specify the IPv4 socket port to be used to communicate with pmcd(1).

       $pmda->set_ipv6_socket(port)
           Specify the IPv6 socket port to be used to communicate with pmcd(1).

       $pmda->set_unix_socket(socket_name)
           Specify the filesystem socket_name path to be used for communication with pmcd(1).

       $pmda->set_user(username)
           Run the PMDA under the username user account, instead of the default (root) user.

HELPER METHODS

       pmda_pmid(cluster, item)
           Construct a Performance Metric Identifier (PMID) from the domain number (passed as an
           argument to the new constructor), the cluster (an integer in the range 0 to 2^12-1)
           and the item (an integer in the range 0 to 2^10-1).

           Every performance metric exported from a PMDA must have a unique PMID.

       pmda_pmid_name(cluster, item)
           Perform a reverse metric identifier to name lookup - given the metric cluster and item
           numbers, returns the metric name string.

       pmda_pmid_text(cluster, item)
           Returns the one-line metric help text string - given the metric cluster and item
           numbers, returns the help text string.

       pmda_inst_name(index, instance)
           Perform a reverse instance identifier to instance name lookup for the instance domain
           identified by index.  Given the internal instance identifier, returns the external
           instance name string.

       pmda_inst_lookup(index, instance)
           Given an internal instance identifier (key) for the instance domain identified by
           index with an associated indom hash, return the value associated with that key.  The
           value can be any scalar value (this includes references, of course, so complex data
           structures can be referenced).

       pmda_units(dim_space, dim_time, dim_count, scale_space, scale_time, scale_count)
           Construct a pmUnits structure suitable for registering a metrics metadata via
           add_metric().

       pmda_config(name)
           Lookup the value for configuration variable name from the /etc/pcp.conf file, using
           pmGetConfig(3).

       pmda_uptime(now)
           Return a human-readable uptime string, based on now seconds since the epoch.

       pmda_long()
           Return either PM_TYPE_32 or PM_TYPE_64 depending on the platform size for a signed
           long integer.

       pmda_ulong()
           Return either PM_TYPE_U32 or PM_TYPE_U64 depending on the platform size for an
           unsigned long integer.

MACROS

       Most of the PM_* macros from the PCP C headers are available.

       For example the type of a metric's value may be directly specified as one of PM_TYPE_32,
       PM_TYPE_U32, PM_TYPE_64, PM_TYPE_U64, PM_TYPE_FLOAT, PM_TYPE_DOUBLE, PM_TYPE_STRING or
       PM_TYPE_NOSUPPORT.

DEBUGGING

       Perl PMDAs do not follow the -D convention of other PCP applications for enabling run-time
       diagnostics and tracing.  Rather the environment variable PCP_PERL_DEBUG needs to be set
       to a string value matching the syntax accepted for the option value for -D elsewhere, see
       __pmParseDebug(3).

       This requires a little trickery.  The pmcd(1) configuration file (PCP_PMCDCONF_PATH from
       /etc/pcp.conf) needs hand editing.  This is best demonstrated by example.

       Replace this line

        foo  242  pipe  binary  python  /somepath/foo.py

       with

        foo  242  pipe  binary  python  \
            sh -c "PCP_PERL_DEBUG=pdu,fetch /usr/bin/python /somepath/foo.py"

SEE ALSO

       perl(1) and PCPIntro(1).

       The PCP mailing list pcp@oss.sgi.com can be used for questions about this module.

       Further details can be found at http://www.pcp.io

AUTHOR

       The Performance Co-Pilot development team.

       Copyright (C) 2014 Red Hat.  Copyright (C) 2008-2010 Aconex.  Copyright (C) 2004 Silicon
       Graphics, Inc.

       This library is free software; you can redistribute it and/or modify it under the terms of
       the GNU General Public License, version 2 (see the "COPYING" file in the PCP source tree
       for further details).