PMDAPROMETHEUS(1) General Commands Manual PMDAPROMETHEUS(1)
pmdaprometheus - Prometheus PMDA
$PCP_PMDAS_DIR/prometheus/pmdaprometheus [-c config] [-t timeout] [-u
user]
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
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.
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.
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 .
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.
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
}
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).
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.
$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).
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).
pmcd(1), pminfo(1), pmlogger(1), pmwebd(1), and
https://prometheus.io/docs/instrumenting/exposition_formats .
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)
|
HTML rendering created 2018-02-02 by Michael Kerrisk, author of The Linux Programming Interface, maintainer of the Linux man-pages project. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH.
|
|