1PCP2INFLUXDB(1)             General Commands Manual            PCP2INFLUXDB(1)
2
3
4

NAME

6       pcp2influxdb - pcp-to-influxdb metrics exporter
7

SYNOPSIS

9       pcp2influxdb  [-CGHIjLnrRvV?]   [-4  action] [-8|-9 limit] [-a archive]
10       [-A align] [--archive-folio  folio]  [-b|-B  space-scale]  [-c  config]
11       [--container  container]  [--daemonize]  [-e derived] [-E password] [-g
12       server] [-h host] [-i instances] [-J rank] [-K spec] [-N predicate] [-O
13       origin]  [-P|-0  precision] [-q|-Q count-scale] [-s samples] [-S start‐
14       time] [-t interval] [-T endtime] [-U username] [-x database] [-X  tags]
15       [-y|-Y time-scale] metricspec [...]
16

DESCRIPTION

18       pcp2influxdb  is  a customizable performance metrics exporter tool from
19       PCP to InfluxDB.  Any available performance metric, live  or  archived,
20       system  and/or  application, can be selected for exporting using either
21       command line arguments or a configuration file.
22
23       pcp2influxdb is a close relative of pmrep(1).  Please refer to pmrep(1)
24       for  the  metricspec  description accepted on pcp2influxdb command line
25       and pmrep.conf(5) for description of the  pcp2influxdb.conf  configura‐
26       tion  file  overall  syntax,  this page describes pcp2influxdb specific
27       options  and  configuration  file   differences   with   pmrep.conf(5).
28       pmrep(1)  also  lists  some usage examples of which most are applicable
29       with pcp2influxdb as well.
30
31       Only the command line options listed on this page are supported,  other
32       options recognized by pmrep(1) are not supported.
33
34       Options  via environment values (see pmGetOptions(3)) override the cor‐
35       responding  built-in  default  values  (if  any).   Configuration  file
36       options  override  the  corresponding  environment  variables (if any).
37       Command line options  override  the  corresponding  configuration  file
38       options (if any).
39

CONFIGURATION FILE

41       pcp2influxdb uses a configuration file with overall syntax described in
42       pmrep.conf(5).  The following options are common with pmrep.conf:  ver‐
43       sion,  source,  speclocal, derived, header, globals, samples, interval,
44       type, type_prefer, ignore_incompat, names_change, instances,  live_fil‐
45       ter,  rank, limit_filter, limit_filter_force, invert_filter, predicate,
46       omit_flat, precision, precision_force, count_scale,  count_scale_force,
47       space_scale, space_scale_force, time_scale, time_scale_force.  The out‐
48       put option is recognized but ignored for pmrep.conf compatibility.
49
50   pcp2influxdb specific options
51       influx_server (string)
52           Specify the URL of InfluxDB server to send the metrics to.   Corre‐
53           sponding    command    line    option    is    -g.     Default   is
54           http://127.0.0.1:8086.
55
56       influx_db (string)
57           Specify the metrics database.  Corresponding command line option is
58           -x.  Default is pcp.
59
60       influx_user (string)
61           Specify  the username for the database.  Corresponding command line
62           option is -U.
63
64       influx_pass (string)
65           Specify the password for the database.  Corresponding command  line
66           option is -E.
67
68       influx_tags (string)
69           Specify  string  of tags to add to the metrics.  Corresponding com‐
70           mand line option is -X.
71

OPTIONS

73       The available command line options are:
74
75       -0 precision, --precision-force=precision
76            Like -P but this option will override per-metric specifications.
77
78       -4 action, --names-change=action
79            Specify which action to take on receiving a  metric  names  change
80            event  during  sampling.  These events occur when a PMDA discovers
81            new metrics sometime after starting up, and informs running client
82            tools  like  pcp2influxdb.   Valid  values  for  action are update
83            (refresh metrics being sampled), ignore (do nothing - the  default
84            behaviour) and abort (exit the program if such an event happens).
85
86       -5, --ignore-unknown
87            Silently ignore any metric name that cannot be resolved.  At least
88            one metric must be found for the tool to start.
89
90       -8 limit, --limit-filter=limit
91            Limit results to instances with values above/below limit.  A posi‐
92            tive  integer  will  include instances with values at or above the
93            limit in reporting.  A negative  integer  will  include  instances
94            with  values  at or below the limit in reporting.  A value of zero
95            performs no limit filtering.  This option will not override possi‐
96            ble per-metric specifications.  See also -J and -N.
97
98       -9 limit, --limit-filter-force=limit
99            Like -8 but this option will override per-metric specifications.
100
101       -a archive, --archive=archive
102            Performance  metric  values  are retrieved from the set of Perfor‐
103            mance Co-Pilot (PCP) archive log files identified by the  argument
104            archive,  which  is a comma-separated list of names, each of which
105            may be the base name of an archive or the name of a directory con‐
106            taining one or more archives.
107
108       -A align, --align=align
109            Force  the initial sample to be aligned on the boundary of a natu‐
110            ral time unit align.  Refer to PCPIntro(1) for a complete descrip‐
111            tion of the syntax for align.
112
113       --archive-folio=folio
114            Read  metric source archives from the PCP archive folio created by
115            tools like pmchart(1) or, less often, manually with mkaf(1).
116
117       -b scale, --space-scale=scale
118            Unit/scale for  space  (byte)  metrics,  possible  values  include
119            bytes, Kbytes, KB, Mbytes, MB, and so forth.  This option will not
120            override possible per-metric specifications.  See  also  pmParseU‐
121            nitsStr(3).
122
123       -B scale, --space-scale-force=scale
124            Like -b but this option will override per-metric specifications.
125
126       -c config, --config=config
127            Specify  the  config  file to use.  The default is the first found
128            of:         ./pcp2influxdb.conf,         $HOME/.pcp2influxdb.conf,
129            $HOME/pcp/pcp2influxdb.conf,                                   and
130            $PCP_SYSCONF_DIR/pcp2influxdb.conf.  For details,  see  the  above
131            section and pmrep.conf(5).
132
133       --container=container
134            Fetch  performance  metrics  from  the specified container, either
135            local or remote (see -h).
136
137       -C, --check
138            Exit before reporting any values, but after parsing the configura‐
139            tion and metrics and printing possible headers.
140
141       --daemonize
142            Daemonize on startup.
143
144       -e derived, --derived=derived
145            Specify  derived  performance  metrics.   If derived starts with a
146            slash (``/'') or with a dot (``.'') it will be  interpreted  as  a
147            derived  metrics  configuration  file, otherwise it will be inter‐
148            preted as comma- or  semicolon-separated  derived  metric  expres‐
149            sions.   For  details  see  pmLoadDerivedConfig(3) and pmRegister‐
150            Derived(3).
151
152       -E password, --db-pass=password
153            Specify the database password.
154
155       -g server, --db-server=server
156            InfluxDB server to send the metrics to.
157
158       -G, --no-globals
159            Do not include global metrics in reporting (see pmrep.conf(5)).
160
161       -h host, --host=host
162            Fetch performance metrics from pmcd(1) on host, rather  than  from
163            the default localhost.
164
165       -H, --no-header
166            Do not print any headers.
167
168       -i instances, --instances=instances
169            Report  only  the  listed  instances  from  current  instances (if
170            present, see also -j).  By  default  all  instances,  present  and
171            future,  are  reported.   This is a global option that is used for
172            all metrics unless a metric-specific instance definition  is  pro‐
173            vided  as part of a metricspec.  By default single-valued ``flat''
174            metrics without multiple instances are still  reported  as  usual,
175            use  -v to change this.  Please refer to pmrep(1) for more details
176            on this option.
177
178       -I, --ignore-incompat
179            Ignore incompatible  metrics.   By  default  incompatible  metrics
180            (that  is,  their  type is unsupported or they cannot be scaled as
181            requested) will cause pcp2influxdb to terminate with an error mes‐
182            sage.   With  this  option  all  incompatible metrics are silently
183            omitted from  reporting.   This  may  be  especially  useful  when
184            requesting non-leaf nodes of the PMNS tree for reporting.
185
186       -j, --live-filter
187            Perform  instance  live filtering.  This allows capturing all fil‐
188            tered instances even if processes  are  restarted  at  some  point
189            (unlike without live filtering).  Performing live filtering over a
190            huge amount of instances will add some internal overhead so a  bit
191            of user caution is advised.  See also -n.
192
193       -J rank, --rank=rank
194            Limit  results to highest/lowest rank instances of set-valued met‐
195            rics.  A positive integer will include highest valued instances in
196            reporting.    A   negative  integer  will  include  lowest  valued
197            instances in reporting.  A value of zero performs no ranking.  See
198            also -8.
199
200       -K spec, --spec-local=spec
201            When fetching metrics from a local context (see -L), the -K option
202            may be used to control the DSO PMDAs that should be made  accessi‐
203            ble.   The  spec  argument  conforms  to  the  syntax described in
204            pmSpecLocalPMDA(3).  More than one -K option may be used.
205
206       -L, --local-PMDA
207            Use a local context to collect metrics from DSO PMDAs on the local
208            host without PMCD.  See also -K.
209
210       -n, --invert-filter
211            Perform  ranking  before live filtering.  By default instance live
212            filtering (when requested, see -j) happens before instance ranking
213            (when  requested, see -J).  With this option the logic is inverted
214            and ranking happens before live filtering.
215
216       -N predicate, --predicate=predicate
217            Specify a comma-separated list of predicate filter reference  met‐
218            rics.   By  default ranking (see -J) happens for each metric indi‐
219            vidually.  With predicates, ranking is done only for the specified
220            predicate  metrics.   When  reporting, rest of the metrics sharing
221            the same instance domain (see PCPIntro(1)) as the  predicate  will
222            include  only  the  highest/lowest ranking instances of the corre‐
223            sponding predicate.
224
225            So for example, using proc.memory.rss  (resident  memory  size  of
226            process) as the predicate metric together with proc.io.total_bytes
227            and mem.util.used as metrics to be reported,  only  the  processes
228            using  most/least (as per -J) memory will be included when report‐
229            ing total bytes written by processes.  Since  mem.util.used  is  a
230            single-valued metric (thus not sharing the same instance domain as
231            the process-related metrics), it will be reported as usual.
232
233       -O origin, --origin=origin
234            When reporting archived metrics, start reporting at origin  within
235            the  time window (see -S and -T).  Refer to PCPIntro(1) for a com‐
236            plete description of the syntax for origin.
237
238       -P precision, --precision=precision
239            Use precision for numeric non-integer output values.  The  default
240            is  to  use  3 decimal places (when applicable).  This option will
241            not override possible per-metric specifications.
242
243       -q scale, --count-scale=scale
244            Unit/scale for count metrics,  possible  values  include  count  x
245            10^-1, count, count x 10, count x 10^2, and so forth from 10^-8 to
246            10^7.  (These values are currently space-sensitive.)  This  option
247            will  not  override  possible per-metric specifications.  See also
248            pmParseUnitsStr(3).
249
250       -Q scale, --count-scale-force=scale
251            Like -q but this option will override per-metric specifications.
252
253       -r, --raw
254            Output raw metric values, do not convert  cumulative  counters  to
255            rates.   This  option will override possible per-metric specifica‐
256            tions.
257
258       -R, --raw-prefer
259            Like -r but this option will not  override  per-metric  specifica‐
260            tions.
261
262       -s samples, --samples=samples
263            The argument samples defines the number of samples to be retrieved
264            and  reported.   If  samples  is  0  or  -s  is   not   specified,
265            pcp2influxdb  will  sample  and  report continuously (in real time
266            mode) or until the end of the set  of  PCP  archives  (in  archive
267            mode).  See also -T.
268
269       -S starttime, --start=starttime
270            When  reporting archived metrics, the report will be restricted to
271            those records logged at or after starttime.  Refer to  PCPIntro(1)
272            for a complete description of the syntax for starttime.
273
274       -t interval, --interval=interval
275            The default update interval may be set to something other than the
276            default 1  second.   The  interval  argument  follows  the  syntax
277            described  in  PCPIntro(1),  and  in  the  simplest form may be an
278            unsigned integer (the implied units in  this  case  are  seconds).
279            See also the -T option.
280
281       -T endtime, --finish=endtime
282            When  reporting archived metrics, the report will be restricted to
283            those records logged before or at endtime.  Refer  to  PCPIntro(1)
284            for a complete description of the syntax for endtime.
285
286            When  used to define the runtime before pcp2influxdb will exit, if
287            no samples is given (see -s) then the number of  reported  samples
288            depends  on  interval (see -t).  If samples is given then interval
289            will be adjusted to allow reporting of samples during runtime.  In
290            case  all  of  -T,  -s,  and  -t are given, endtime determines the
291            actual time pcp2influxdb will run.
292
293       -U username, --db-user=username
294            Specify the database username.
295
296       -v, --omit-flat
297            Omit single-valued ``flat'' metrics from reporting, only  consider
298            set-valued  metrics  (i.e.,  metrics  with  multiple  values)  for
299            reporting.  See -i and -I.
300
301       -V, --version
302            Display version number and exit.
303
304       -x database, --db-name=database
305            Specify the metrics database name.
306
307       -X tags, --db-tags=tags
308            Specify strings of tags to add to the metrics.
309
310       -y scale, --time-scale=scale
311            Unit/scale for time metrics, possible values include nanosec,  ns,
312            microsec,  us,  millisec,  ms,  and so forth up to hour, hr.  This
313            option will not override possible per-metric specifications.   See
314            also pmParseUnitsStr(3).
315
316       -Y scale, --time-scale-force=scale
317            Like -y but this option will override per-metric specifications.
318
319       -?, --help
320            Display usage message and exit.
321

FILES

323       pcp2influxdb.conf
324              pcp2influxdb configuration file (see -c)
325

PCP ENVIRONMENT

327       Environment variables with the prefix PCP_ are used to parameterize the
328       file and directory names used by PCP.  On each installation,  the  file
329       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
330       $PCP_CONF variable may be used to specify an alternative  configuration
331       file, as described in pcp.conf(5).
332
333       For environment variables affecting PCP tools, see pmGetOptions(3).
334

SEE ALSO

336       mkaf(1),  PCPIntro(1),  pcp(1),  pcp2elasticsearch(1), pcp2graphite(1),
337       pcp2json(1),  pcp2spark(1),  pcp2xlsx(1),  pcp2xml(1),   pcp2zabbix(1),
338       pmcd(1),   pminfo(1),  pmrep(1),  pmGetOptions(3),  pmSpecLocalPMDA(3),
339       pmLoadDerivedConfig(3), pmParseUnitsStr(3), pmRegisterDerived(3), LOGA‐
340       RCHIVE(5), pcp.conf(5), pmns(5) and pmrep.conf(5).
341
342
343
344Performance Co-Pilot                  PCP                      PCP2INFLUXDB(1)
Impressum