NAME | SYNOPSIS | DESCRIPTION | CONFIGURATION SOURCES | URL SOURCES | SCRIPTED SOURCES | METRIC NAMING | DYNAMIC METRIC NAMES | LIMITATIONS | INSTALLATION | FILES | PCP ENVIRONMENT | SEE ALSO | COLOPHON

PMDAPROMETHEUS(1)          General Commands Manual         PMDAPROMETHEUS(1)

NAME         top

       pmdaprometheus - Prometheus PMDA

SYNOPSIS         top

       $PCP_PMDAS_DIR/prometheus/pmdaprometheus [-c config] [-t timeout] [-u
       user]

DESCRIPTION         top

       pmdaprometheus is a Performance Metrics Domain Agent (PMDA) which
       creates PCP metrics from Prometheus endpoints, which provide HTTP
       based access to application metrics.  The default config directory is
       $PCP_PMDAS_DIR/prometheus/config.d/, see SOURCES below.  The default
       URL fetch timeout is 2 seconds.  The default user, if not specified
       with the -u option, is the current user.

       Further details on the Prometheus exposition format can be found at
       https://prometheus.io/docs/instrumenting/exposition_formats 

CONFIGURATION SOURCES         top

       As it runs, pmdaprometheus periodically recursively scans the
       $PCP_PMDAS_DIR/prometheus/config.d directory (or the directory
       specified with the -c option), looking for source URL files (*.url)
       and executable scripts or binaries.  Any files that do not have the
       .url suffix or are not executable, are ignored - this allows
       documentation files such as "README" and non-executable "common"
       script function definitions to be present without being considered as
       config files.

URL SOURCES         top

       Each .url file found in the config directory or sub-directory
       contains one complete HTTP or HTTPS URL at which pmdaprometheus can
       reach a Prometheus endpoint.  Local file access is also supported
       with a conventional file://somepath/somefile URL, in which case
       somepath/somefile should contain prometheus formatted metric data.

       A remote server does not have to be up or stay running - the PMDA
       tolerates remote URLs that may come and go over time.  The PMDA will
       relay data and metadata when/if they are available, and will return
       errors when/if they are down.  PCP metric IDs and instance domain
       names and IDs are saved and persistently restored when individual
       metric sources become available and/or when the PMDA is restarted.

SCRIPTED SOURCES         top

       Likewise, executable scripts present in the
       $PCP_PMDAS_DIR/prometheus/config.d directory or sub-directories will
       be executed and the stdout stream containing prometheus formatted
       metric data will be parsed as though it had come from a URL or file.
       The stderr stream from a script will be sent to the PMDA log file,
       which by default can be found in $(PCP_LOG_DIR)/pmcd/prometheus.log.

       A simple example of a scripted config entry follows:

          #! /bin/sh
          awk '{
              print("# HELP loadavg local load average")
              print("# Type loadavg gauge")
              printf("loadavg {interval=\"1-minute\"} %.2f\n", $1)
              printf("loadavg {interval=\"5-minute\"} %.2f\n", $2)
              printf("loadavg {interval=\"15-minute\"} %.2f\n", $3)
          }' /proc/loadavg

       This script produces the following prometheus formatted metric data
       when run :

          # HELP loadavg local load average
          # Type loadavg gauge
          loadavg {interval="1-minute"} 0.12
          loadavg {interval="5-minute"} 0.27
          loadavg {interval="15-minute"} 0.54

       If the above script was saved and made executable in a file named
       (assuming default settings)
       /var/lib/pcp/pmdas/prometheus/config.d/local/system.sh then this
       would result in a new PCP metric named
       prometheus.local.system.loadavg which would have three instances for
       the current load average values: 1-minute, 5-minute and 15-minute.

       Scripted config entries may produce more than one PCP leaf metric
       name.  For example, the above "system.sh" script could also export
       other metrics such as CPU statistics, by reading /proc/stat on the
       local system.  Such additional metrics would appear as peer metrics
       in the same PCP metric subtree.  In the case of CPU counters, the
       metric type definition should be counter, not guage.  For full
       details of the prometheus exposition formats, see
       https://prometheus.io/docs/instrumenting/exposition_formats .

METRIC NAMING         top

       All metrics from a file named FOO.*  will be exported as PCP metrics
       with the prometheus.FOO metric name prefix.  Therefore, the FOO name
       must be a valid non-leaf name for PCP PMNS metric names.  If the FOO
       name has multiple dot-separated components, the resulting PMNS names
       will include those components and care is needed to ensure there are
       no overlapping definitions, e.g. metrics returned by foo.bar.url may
       overlap or conflict with metrics returned by foo.bar.baz.url.

       Config file entries (URLs or scripts) found in subdirectories of the
       config directory will also result in hierarical metric names.  For
       example, a config file named
       /var/lib/pcp/pmda/prometheus/config.d/mysource/latency/get.url will
       result in metrics being created (by fetching that source URL) below
       prometheus.mysource.latency.get in the PCP namespace.  Scripts found
       in subdirectories of the config directory similarly result in
       hirarchical PCP metric names.

DYNAMIC METRIC NAMES         top

       As described above, changes and new additions can be made to files in
       the configuration directory without having to restart the PMDA.
       These changes are detected automatically and the PCP metric names
       below prometheus in the PMNS will be updated accordingly, i.e. new
       metrics will be dynamically added and/or existing metrics removed.
       In addition, the prometheus PMDA honors the PMCD_NAMES_CHANGE
       protocol that was inntroduced in PCP version 4.0 and later.  This
       protocol extension is only recognised by PCP version 4 clients.  In
       particular, if prometheus metrics are being logged by a PCP v4.0 or
       later pmlogger(1), new metrics that appear as a result of changes in
       the PMDA configuration directory will automatically start to be
       logged, provided the root of the prometheus PMDA namespace is
       configured for logging in the pmlogger configuration file.  See
       pmlogger(1) for details.  An example of such a pmlogger configuration
       file is :

          log mandatory on 2 second {
               # log all metrics below the root of the prometheus namespace
               prometheus
          }

LIMITATIONS         top

       pmdaprometheus and libpcp internals impose some numerical constraints
       about the number of sources (4095), metrics (1024) within each
       source, and instance domain instances for each metric (4194304).

INSTALLATION         top

       Install the Prometheus PMDA by using the Install script as root:

             # cd $PCP_PMDAS_DIR/prometheus
             # ./Install

       To uninstall, do the following as root:

             # cd $PCP_PMDAS_DIR/prometheus
             # ./Remove

       pmdaprometheus is launched by pmcd(1) and should never be executed
       directly. The Install and Remove scripts notify pmcd(1) when the
       agent is installed or removed.

       When scripts and .url files are added, removed or changed in the
       configuration directory, it is usually not necessary to restart the
       PMDA - the changes should be detected and managed on subsequent PCP
       requests to the PMDA.

FILES         top

       $PCP_PMDAS_DIR/prometheus/Install
           installation script for the pmdaprometheus agent

       $PCP_PMDAS_DIR/prometheus/Remove
           undo installation script for the pmdaprometheus agent

       $PCP_PMDAS_DIR/prometheus/config.d/
           contains URLs and scripts used by the pmdaprometheus agent as
           sources of prometheus metric data.

       $PCP_LOG_DIR/pmcd/prometheus.log
           default log file for error messages from pmdaprometheus

       $PCP_VAR_DIR/config/144.*
           files containing internal tables for metric and instance ID
           number persistence (domain 144).

PCP ENVIRONMENT         top

       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).

SEE ALSO         top

       pmcd(1), pminfo(1), pmlogger(1), pmwebd(1), and
       https://prometheus.io/docs/instrumenting/exposition_formats .

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.
       Information about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a bug report for this manual page, send it to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2018-02-02.  (At that time, the date of the most recent commit that
       was found in the repository was 2018-02-02.)  If you discover any
       rendering problems in this HTML version of the page, or you believe
       there is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       man-pages@man7.org

Performance Co-Pilot                 PCP                   PMDAPROMETHEUS(1)