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

NAME

6       pmnewlog - stop and restart archive logging for PCP performance metrics
7

SYNOPSIS

9       $PCP_BINADM_DIR/pmnewlog  [-a  accessfile]  [-C saveconfig] [-c config‐
10       file] [-N] [-n pmnsfile]  [-P]  [-p  pid]  [-s]  [-V]  [other  pmlogger
11       options] archive
12

DESCRIPTION

14       pmnewlog  may  be used to stop and restart a running instance of pmlog‐
15       ger(1).  This is most useful for managing multiple sets of  Performance
16       Co-Pilot  (PCP) archive logs.  These archive logs record the history of
17       performance metric values that may be  ``played  back''  by  other  PCP
18       tools,  and  they  form the basis of the VCR paradigm and retrospective
19       performance analysis services common to the PCP toolkit.
20
21       In normal usage, pmnewlog would be executed by cron(1) in the wee hours
22       to terminate one PCP archive log and start another, i.e. to perform log
23       rotation.
24
25       Even more common, would be the execution of pmnewlog from the  PCP  ar‐
26       chive  management  script pmlogger_daily(1).  In this case, direct end-
27       user execution of pmnewlog is most unlikely.
28
29       The mandatory argument archive is the base name for the physical  files
30       that will constitute the new archive log.
31
32       The  pmlogger  instance  to be stopped and restarted must be running on
33       the same system as pmnewlog and  is  either  the  primary  logger  (the
34       default) or the logger with pid as specified by the -p option.
35
36       If  the -n option is specified, then pmnewlog will use the namespace in
37       the pmnsfile, rather than the default Performance  Metrics  Name  Space
38       (PMNS).
39
40       If  no  -c option is specified, pmnewlog will use pmlc(1) to connect to
41       the  running  pmlogger(1)  and  so  determine  all  those  metrics  and
42       instances that are subject to mandatory logging or advisory on logging,
43       and the associated logging frequencies.  This information  is  used  to
44       synthesize  a  new pmlogger(1) configuration file.  If the -n option is
45       specified, it will also be used for these interactions with pmlc(1).
46
47       If the -c option is specified, pmlogger(1) will be restarted with  con‐
48       figfile  as  the  configuration file.  Normally configfile would be the
49       same configuration file used to start pmlogger(1) in the  first  place,
50       however  note  that  since pmlogger(1) is restarted, any changes to the
51       logging status made using pmlc(1) will be lost, unless these have  also
52       been reflected in changes to configfile.
53
54       If  configfile  does  not exist, then a search is made in the directory
55       $PCP_VAR_DIR/config/pmlogger for a file of the same name, and if  found
56       that  file is used, e.g. if config.mumble does not exist in the current
57       directory and the file $PCP_VAR_DIR/config/pmlogger/config.mumble  does
58       exist,  then  -c config.mumble and -c $PCP_VAR_DIR/config/pmlogger/con‐
59       fig.mumble are equivalent.
60
61       Access controls specifications for the  new  pmlogger(1)  instance  may
62       optionally  be  provided via the -a option.  The contents of accessfile
63       should start with the literal token [access] and conform to the  syntax
64       of the access controls section as described for pmlogger(1).
65
66       The  -C option may be used to save the configuration file that pmnewlog
67       passes to the newly launched pmlogger(1).
68
69       If the pmlogger(1) instance needs to be started under  the  control  of
70       pmsocks(1)  to  connect to a pmcd through a firewall, the -s option may
71       be used.
72
73       The -V option enables verbose reporting of the activity.  By default no
74       output  is  generated unless some error or warning condition is encoun‐
75       tered.
76
77       The -N option enables a ``show me'' mode, where the actions are echoed,
78       but not executed, in the style of ``make -n''.  Using -N in conjunction
79       with -V maximizes the diagnostic capabilities for debugging.
80
81       The other pmlogger options are as described for pmlogger(1).  Note that
82       pmnewlog does not support the following options of pmlogger(1).
83
84       -h host
85              pmnewlog determines the host to which the new pmlogger(1) should
86              connect based upon the  current  host  connection  for  the  old
87              pmlogger(1).
88
89       -s samples
90              The  new  pmlogger(1) is expected to be long running, and the -s
91              option of pmnewlog takes precedence.
92
93       -T runtime
94              The new pmlogger(1) is expected to be long running
95
96       -V version
97              The new pmlogger will always create the latest version  PCP  ar‐
98              chive format, and the -V option of pmnewlog takes precedence.
99
100       -x fd  The  launched  pmlogger  cannot  be  controlled  by pmRecordCon‐
101              trol(3).
102

EXAMPLE

104       The following sh(1) script could be executed by  root  via  cron(1)  to
105       start a new set of archive logs for the primary logger each evening.  A
106       more   complete   version   of   this   script   may   be   found    in
107       $PCP_BINADM_DIR/pmlogger_daily,  and  is  documented in the manual page
108       for pmlogger_daily(1).
109
110               #!/bin/sh
111               # start new logs for PCP primary logger on this host
112
113               # standard place for logs
114               LOGDIR=$PCP_LOG_DIR/pmlogger/`hostname`
115
116               # each new log is named yymmdd.hh.mm
117               LOGNAME=`date "+%Y%m%d.%H.%M"`
118
119               # do it
120               [ ! -d $LOGDIR ] && mkdir -p $LOGDIR
121               cd $LOGDIR
122               $PCP_BINADM_DIR/pmnewlog -l $LOGDIR/pmlogger.log $LOGDIR
123

FILES

125       archive.meta
126                 metadata (metric descriptions, instance  domains,  etc.)  for
127                 the archive log
128       archive.0 initial  volume  of  metrics  values (subsequent volumes have
129                 suffixes 1, 2, ...)
130       archive.index
131                 temporal index to support rapid random access  to  the  other
132                 files in the archive log
133       $PCP_BINADM_DIR/pmlogger_daily
134                 sample script to rotate archives for a number of loggers
135

PCP ENVIRONMENT

137       Environment variables with the prefix PCP_ are used to parameterize the
138       file and directory names used by PCP.  On each installation,  the  file
139       /etc/pcp.conf  contains  the  local  values  for  these variables.  The
140       $PCP_CONF variable may be used to specify an alternative  configuration
141       file, as described in pcp.conf(4).
142

SEE ALSO

144       PCPIntro(1),   pmcd(1),   pmdumplog(1),  pmlc(1),  pmlogger(1),  pmlog‐
145       ger_daily(1), pmsocks(1), pcp.conf(4) and pcp.env(4).
146

DIAGNOSTICS

148       Due to the precious nature of the  archive  logs,  pmnewlog  is  rather
149       paranoid  in  its  checking  and  validation, and will try very hard to
150       ensure that an appropriately configured pmlogger(1) can  be  restarted,
151       before terminating the existing pmlogger(1).
152
153       As  a  consequence  of this checking, pmnewlog tends to generate rather
154       verbose error and warning messages.
155

CAVEATS

157       If no configfile is specified, the method for synthesizing a configura‐
158       tion file using a pmlc(1) connection to the existing pmlogger(1) is, of
159       necessity, incomplete.  In particular, for metrics with dynamic  under‐
160       lying  instance domains, it is not possible to identify a configuration
161       that logs all instances of a metric all of the time, so rather the syn‐
162       thesized  configuration  file requests the continued logging of the set
163       of instances that exist at the  time  pmlogger(1)  is  interrogated  by
164       pmnewlog.
165
166       If  this  situation  is a concern, a fixed configuration file should be
167       used, and passed to pmnewlog via the -c option.
168
169
170
171Performance Co-Pilot                  SGI                          PMNEWLOG(1)
Impressum