Many PCP tools are designed to operate in some time window of
interest, for example to define a termination time for real-time
monitoring or to define a start and end time within a set of PCP
archive logs.
In the absence of the -O (or --origin) and -A (or --align)
options to specify an initial sample time origin and time
alignment (see above), the PCP application will retrieve the
first sample at the start of the time window.
The following options may be used to specify a time window of
interest.
-S starttime, --start=starttime
By default the time window commences immediately in real-
time mode, or coincides with time at the start of the set
of PCP archive logs in archive mode. The -S or --start
option may be used to specify a later time for the start
of the time window.
The starttime parameter may be given in one of three forms
(interval is the same as for the -t or --interval option
as described above, datetime is described below):
interval
To specify an offset from the current time (in
real-time mode) or the beginning of a set of PCP
archives (in archive mode) simply specify the
interval of time as the argument. For example -S
30min will set the start of the time window to be
exactly 30 minutes from now in real-time mode, or
exactly 30 minutes from the start of a set of PCP
archives.
-interval
To specify an offset from the end of a set of PCP
archive logs, prefix the interval argument with a
minus sign. In this case, the start of the time
window precedes the time at the end of the set of
archives by the given interval. For example -S
-1hour will set the start of the time window to be
exactly one hour before the time of the last sample
in a set of PCP archive logs.
@datetime
To specify the calendar date and time (local time
in the reporting timezone) for the start of the
time window, use the datetime syntax preceded by an
at sign. Refer to the datetime description below
for detailed information.
-T endtime, --finish=endtime
By default the end of the time window is unbounded (in
real-time mode) or aligned with the time at the end of a
set of PCP archive logs (in archive mode). The -T or
--finish option may be used to specify an earlier time for
the end of the time window.
The endtime parameter may be given in one of three forms
(interval is the same as for the -t or --interval option
as described above, datetime is described below):
interval
To specify an offset from the start of the time
window simply use the interval of time as the
argument. For example -T 2h30m will set the end of
the time window to be 2 hours and 30 minutes after
the start of the time window.
-interval
To specify an offset back from the time at the end
of a set of PCP archive logs, prefix the interval
argument with a minus sign. For example -T -90m
will set the end of the time window to be 90
minutes before the time of the last sample in a set
of PCP archive logs.
@datetime
To specify the calendar date and time (local time
in the reporting timezone) for the end of the time
window, use the datetime syntax preceded by an at
sign. Refer to the datetime description below for
detailed information.
-O origin, --origin=origin
By default samples are fetched from the start of the time
window (see description of -S or --start option) to the
end of the time window (see description of -T or --finish
option). The -O or --origin option allows the
specification of an origin within the time window to be
used as the initial sample time. This is useful for
interactive use of a PCP tool with the pmtime(1) VCR
replay facility.
The origin argument accepted by -O (or --origin) conforms
to the same syntax and semantics as the starttime argument
for the -T (or --finish) option.
For example --origin -0 specifies that the initial
position should be at the end of the time window; this is
most useful when wishing to replay ``backwards'' within
the time window.
The datetime argument for the -O (or --origin), -S (or --start)
and -T (or --finish) options consists of:
date time zone day relative
A date can be one of: YY-MM-DD, MM/DD/YY, DD Month YYYY, or Month
DD YYYY. A time can be one of: HH:MM:SS, HH:MM. HH:MM can use
either the 12 hour (via an am or pm suffix) or 24 hour
convention. A day of the week can be a spelled out day of the
week, optionally preceded by an ordinal number such as second
Tuesday. A zone is a time zone value as specified by the
tzselect(8) command. A relative time can be a time unit that is:
preceded by a cardinal number such as 1 year or 2 months,
preceded by one of the time words this or last, or succeeded by
the time word ago. A relative time can also be one of the time
words: yesterday, today, tomorrow, now. Examples of datetime
strings are: 1996-03-04 13:07:47 EST Mon, 1996-03-05 14:07:47 EST
-1hour, Mon Mar 4 13:07:47 1996, Mar 4 1996, Mar 4, Mar,
13:07:50 or 13:08.
For any missing low order fields, the default value of 0 is
assumed for hours, minutes and seconds, 1 for day of the month
and Jan for months. Hence, the following are equivalent: --start
'@ Mar 1996' and --start '@ Mar 1 00:00:00 1996'.
If any high order fields are missing, they are filled in by
starting with the year, month and day from the current time
(real-time mode) or the time at the beginning of the set of PCP
archive logs (archive mode) and advancing the time until it
matches the fields that are specified. So, for example if the
time window starts by default at ``Mon Mar 4 13:07:47 1996'',
then --start @13:10 corresponds to 13:10:00 on Mon Mar 4, 1996,
while --start @10:00 corresponds to 10:00:00 on Tue Mar 5, 1996
(note this is the following day).
For greater precision than afforded by datetime(3), the seconds
component may be a floating point number.
If a timezone is not included in a datetime then there ares
several interpretations available depending on the other command
line options used. The default is to use the local timezone on
the system where the PCP tool is being run. A -Z or --timezone
option specifies an explicit timezone, else a -z or --hostzone
option changes the timezone to the local timezone at the host
that is the source of the performance metrics.
