From 47e6e7c84f008a53061e661f31ae96629bc694ef Mon Sep 17 00:00:00 2001 From: Igor Pashev Date: Sun, 26 Oct 2014 12:33:50 +0400 Subject: Debian 3.9.10 --- man/man1/pmchart.1 | 655 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 655 insertions(+) create mode 100644 man/man1/pmchart.1 (limited to 'man/man1/pmchart.1') diff --git a/man/man1/pmchart.1 b/man/man1/pmchart.1 new file mode 100644 index 0000000..3cd2a40 --- /dev/null +++ b/man/man1/pmchart.1 @@ -0,0 +1,655 @@ +.\" Copyright (c) 2006, Ken McDonell. All Rights Reserved. +.\" Copyright (c) 2008, Aconex. All Rights Reserved. +.\" Copyright (c) 2014, Red Hat. +.TH PMCHART 1 "" "Performance Co-Pilot" +.SH NAME +\f3pmchart\f1 \- strip chart tool for Performance Co-Pilot +.SH SYNOPSIS +\f3pmchart\f1 +[\f3\-CVWz\f1] +[\f3\-A\f1 \f2align\f1] +[\f3\-a\f1 \f2archive\f1] +[\f3\-c\f1 \f2configfile\f1] +[\f3\-f\f1 \f2fontfamily\f1] +[\f3\-F\f1 \f2fontsize\f1] +[\f3\-g\f1 \f2geometry\f1] +[\f3\-g\f1 \f2geometry\f1] +[\f3\-h\f1 \f2host\f1] +[\f3\-o\f1 \f2outfile\f1] +[\f3\-O\f1 \f2offset\f1] +[\f3\-p\f1 \f2port\f1] +[\f3\-s\f1 \f2samples\f1] +[\f3\-S\f1 \f2starttime\f1] +[\f3\-T\f1 \f2endtime\f1] +[\f3\-t\f1 \f2interval\f1] +[\f3\-v\f1 \f2visible\f1] +[\f3\-Z\f1 \f2timezone\f1] +[\f2sources\f1...] +.SH DESCRIPTION +.B pmchart +is a graphical utility that plots performance metrics values +available through the facilities of the Performance Co-Pilot (PCP). +Multiple charts can be displayed simultaneously, either aligned +on the unified time axis (X-axis), and through the use of multiple +interface Tabs. +.PP +Metric values can be sourced from one or more live hosts +(simultaneously). Alternatively, one or more PCP archives +can be used as a source of historical data. +See +.BR PCPIntro (1) +for an in-depth discussion of the capabilities of the PCP +framework, many of which are used by +.B pmchart. +.PP +Many aspects of the behaviour of +.B pmchart +can be customised through the interface. +In particular, the use of "views" (refer to the section describing +VIEWS later in this document) +allows predefined sets of metrics and charting parameters +like colors, scaling, titles, legends, and so on to be stored for +later use, or use with different hosts and archives. +In addition, the Preferences dialog allows customisations to the +rest of the +.B pmchart +user interface to be saved and restored between different invocations +of the tool. +This allows the default background color, highlight color, contents +and location of the toolbar, and many other aspects to be configured. +.PP +.B pmchart +makes extensive use of the +.BR pmtime (1) +utility for time control, refer to the +.B pmtime +manual page for further details of its operation. +.PP +Options which control the default source, timing and layout of the +.B pmchart +window are as follows: +.TP 5 +.B \-a +Performance metric values are retrieved from the Performance Co-Pilot +(PCP) archive log file identified by the base name archive, by default. +The initial Tab created will be an archive mode Tab. +Multiple +.B \-a +options can be presented, and the list of archives is used for sourcing +metric values. +Any \f2sources\f1 listed on the command line are assumed to be archives +if this option is used. +.TP +.B \-c +.I configfile +specifies an initial view to load, using the default source of metrics. +Multiple +.B \-c +views can be specified, and they will all be opened in the +default Tab with the default source of metrics. +.TP +.B \-C +Used with +.BR \-c , +the view(s) are parsed, any errors are reported, and the tool exits. +This is primarily intended for testing purposes. +If a second +.B \-C +option is presented, +.B pmchart +also connects to +.BR pmcd (1) +to check the semantics of metrics. +.TP +.B \-f +Specify the default font +.I family +to be used in several chart components, +such as the chart title, legend, and Y-axis label. +The default value is "Sans Serif". +This setting does not affect the rest of the user interface, where +the value is inherited from the environment in which +.B pmchart +operates, and differs according to the look-and-feel of each +platform. +.TP +.B \-F +Specify the default font +.I point +size to be used in several chart components, +such as the chart title, legend, and Y-axis label. +The default is platform dependent, but is either 7, 8 or 9. +This setting does not affect the rest of the user interface. +.TP +.B \-g +Generate image with the specified +.I geometry +(width and height). +This option is only useful when used in conjunction with the +.B \-o +option for generating an output image. +The +.I geometry +argument takes the form "WxH" (e.g. 240x120). +.TP +.B \-h +Current performance metric values are retrieved from the nominated +.I host +machine by default. +Multiple +.B \-h +options can be presented, and the list of hosts is used for sourcing +metric values. +Any \f2sources\f1 listed on the command line are assumed to be hosts +if this option is used. +.TP +.B \-o +Generate an image file named +.IR outfile , +and then exit. +This is most useful when run with an archive and one or more views. +The generated image will be in the format specified as the file +extension (automatically determined from +.IR outfile ). +If no extension can be determined, then the GIF format is used and +the generated file is named with this extension. +The supported image file formats include: bmp, jpeg, jpg, png, ppm, +tif, tiff, xbm, and xpm. +.TP +.B \-p +.I port +number for connection to an existing +.B pmtime +time control process. +.TP +.B \-s +Specifies the number of +.I samples +that will be retained before discarding old data (replaced by +new values at the current time position). +This value can subsequently be modified through the Edit Tab +dialog. +.TP +.B \-t +Sets the inital update +.I interval +to something other than the default 1 second. +The +.I interval +argument follows the syntax described in +.BR PCPIntro (1), +and in the simplest form may be an unsigned integer (the implied +units in this case are seconds). +.TP +.B \-v +Sets the inital visible +.I samples +that will be displayed in all charts in the default Tab. +This value must be less than or equal to the total number +of samples retained (the +.B \-s +value). +.TP +.B \-V +Display pmchart version number and exit +.TP +.B \-W +Export images using an opaque(white) background +.TP +.B \-Z +By default, +.B pmtime +reports the time of day according to the local timezone on the system +where +.B pmchart is run. +The +.B \-Z +option changes the timezone to +.I timezone +in the format of the environment variable TZ as described in +.BR environ (5). +.TP +.B \-z +Change the reporting timezone to the local timezone at the host +that is the source of the performance metrics, as identified via +either the +.B \-h +or +.B \-a +options. +.PP +The +.BR \-S , +.BR \-T , +.B \-O +and +.B \-A +options may be used to define a time window to +restrict the samples retrieved, set an initial origin within the time +window, or specify a "natural" alignment of the sample times; refer +to +.BR PCPIntro (1) +for a complete description of these options. +.SH VIEWS +The primary +.B pmchart +configuration file is the "view", which allows the metadata +associated with one or more charts to be saved in the filesystem. +This metadata describes all aspects of the charts, including +which PCP metrics and instances are to be used, which hosts, which +colors, the chart titles, use of chart legends, and much more. +.PP +From a conceptual point of view, there are two classes of view. +These views share the same configuration file format \- refer +to a later section for a complete description of this format. +The differences lie in where they are installed and how they +are manipulated. +.PP +The first class, the "system" view, is simply any view that is +installed as part of the +.B pmchart +package. +These are stored in +.I $PCP_VAR_DIR/config/pmchart. +When the +.I "File\(->Open View" +dialog is displayed, it is these views that are initially listed. +The system views cannot be modified by a normal user, and should +not be modified even by a user with suitable priviledges, as they +will be overwritten during an upgrade. +.PP +The second class of view is the "user" view. +These views are created on-the-fly using the +.I "File\(->Save View" +dialog. +This is a mechanism for individual users to save their commonly +used views. +Access to these views is achieved through the +.I "File\(->Open View" +dialog, as with the system views. +Once the dialog is opened, the list of views can be toggled between +user and system views by clicking on the two toggle buttons in the +top right corner. +User views are stored in +.I $HOME/.pcp/pmchart. +.SH TABS +.B pmchart +provides the common user interface concept of the Tab, which +is most prevalent in modern web browsers. +Tabs allow +.B pmchart +to update many more charts than the available screen real estate +allows, by providing a user interface mechanism to stack (and +switch between) different vertical sets of charts. +Switching between Tabs is achieved by clicking on the Tab labels, +which are located along the top of the display beneath the Menu +and Tool bars). +.PP +Each Tab has a mode of operation (either live or archive \- +.B pmchart +can support both modes simultaneously), the total number of +samples and currently visible points, and a label describing +the Tab which is displayed at the top of the +.B pmchart +window. +New Tabs can be created using the +.I "File\(->Add Tab" +dialog. +.PP +In order to save on vertical screen real estate, note that the user +interface element for changing between different Tabs (and its label) +are only displayed when more than one Tab exists. +A Tab can be dismissed using the +.I "File\(->Close Tab" +menu, which removes the current Tab and any charts it contained. +.SH IMAGES and PRINTING +A static copy of the currently displayed vertical series of charts +can be captured in two ways. +.PP +When the intended display device is the screen, the +.I "File\(->Export" +menu option should be used. +This allows exporting the charts in a variety of image formats, +including PNG, JPEG, GIF, and BMP. +The image size can be scaled up or down in any dimension. +.PP +Alternatively, when the intended display device is paper, the +.I "File\(->Print" +menu option can be used. +This supports the usual set of printing options (choice of printer, +grayscale/color, landscape/portrait, scaling to different paper sizes, +etc), +and in addition allows printing to the intermediate printer formats +of PostScript and Portable Document Format (PDF). +.SH RECORDING +It is possible to make a recording of a set of displayed charts, +for later playback through +.B pmchart +or any of the other Performance Co-Pilot tools. +The +.I "Record\(->Start" +functionality is simple to configure through the user interface, +and allows fine-tuning of the recording process (including record +frequencies that differ to the +.B pmchart +update interval, alternate file locations, etc). +.PP +.B pmchart +produces recordings that are compatible with the PCP +.BR pmafm (1) +replay mechanism, for later playback via a new instance of +.BR pmchart . +In addition, when recording through +.B pmchart +one can also replay the recording immediately, as on termination +of the recording (through the +.I "Record\(->Stop" +menu item), an archive mode Tab will be created with the captured view. +.PP +Once recording is active in a Live Tab, the Time Control status +button in the bottom left corner of the +.B pmchart +window is displayed with a distinctive red dot. +At any time during a +.B pmchart +recording session, the amount of space used in the filesystem by +that recording can be displayed using the +.I "Record\(->Query" +menu item. +.PP +Finally, the +.I "Record\(->Detach" +menu option provides a mechanism whereby the recording process can +be completely divorced from the running +.B pmchart +process, and allowed to continue on when +.B pmchart +exits. +A dialog displaying the current size and estimated rate of growth for +the recording is presented. +On the other hand, if +.B pmchart +is terminated while recording is in process, then the recording process +will prompt the user to choose immediate cessation of recording or for +it to continue on independently. +.PP +All of the record mode services available from +.B pmchart +are implemented with the assistance of the base Performance Co-Pilot +logging services \- refer to +.BR pmlogger (1) +and +.BR pmafm (1) +for an extensive description of the capabilities of these tools. +.SH CONFIGURATION FILE SYNTAX +.de ES +.ft CW +.nf +.in +0.5i +.. +.de EE +.ft R +.br +.in +.fi +.. +.PP +.B pmchart +loads predefined chart configurations (or "views") from external +files that conform to the following rules. In the descriptions below +keywords (shown in \f(CBbold\fP) may appear in upper, lower or +mixed case, elements shown in \f(CW[stuff]\fP are optional, and +user-supplied elements are shown as \f(CW\fP. +A vertical bar (|) is used where syntactic elements are alternatives. +Quotes (") +may be used to enclose lexical elements that may contain white space, +such as titles, labels and instance names. +.IP 1. 0.3i +The first line defines the configuration file type and should be +.ES +\f(CB#kmchart\fP +.EE +although +.B pmchart +provides backwards compatibility for the older +.B pmchart +view formats with an initial line of +.ES +\f(CB#pmchart\fP +.EE +.IP 2. 0.3i +After the first line, lines beginning with "#" as the first +non-white space character are treated as comments and skipped. +Similarly blank lines are skipped. +.IP 3. 0.3i +The next line should be +.ES +\f(CBversion\fP +.EE +where \f(CW\fP depends on the configuration file type, and +is \f(CB1\fP for \f(CBpmchart\fP else \f(CB1.1\fP, \f(CB1.2\fP or +\f(CB2.0\fP for \f(CBpmchart\fP. +.RS +The \f(CW\fP part is optional (and ignored) +for \fBpmchart\fP configuration +files, but required for the \fBpmchart\fP configuration files, and +is of the form +.ES +\f(CBhost\fP \f(CBliteral\fP +.EE +or +.ES +\f(CBhost\fP \f(CBdynamic\fP +.EE +.RE +.IP 4. 0.3i +A configuration contains one or more charts defined as follows: +.ES +\f(CBchart\fP [\f(CBtitle\fP ] \f(CBstyle\fP <style> <options> +.EE +If specified, the title will appear centred and above the graph area +of the chart. +The \f(CW<title>\fP is usually enclosed in quotes (") and if it +contains the sequence "%h" this will be replaced by the short form +of the hostname for the default source of metrics at the time +this chart was loaded. Alternatively, "%H" can be used to insert +the full host name. If the hostname appears to be an inet or IPv6 +address, no shortening will be attempted; it will be used as-is in +both replacement cases. +After the view is loaded, the title visibility and setting +can be manipulated using the +.I "Chart Title" +text box in the +.I "Edit\(->Chart" +dialog. +.RS +.PP +The \f(CW<style>\fP controls the initial plotting style of the chart, and +should be one of the keywords \f(CBplot\fP (line graph), \f(CBbar\fP, +\f(CBstacking\fP (stacked bar), +\f(CBarea\fP or \f(CButilization\fP. +After the view is loaded, the plotting style can be changed using the +.I "Edit\(->Chart" +Style dropdown list. +.PP +The \f(CW<options>\fP are zero or more of the optional elements: +.ES +[\f(CBscale\fP [from] <ymin> [to] <ymax>] [\f(CBlegend\fP <onoff>] +.EE +If \f(CBscale\fP is specfied, the vertical scaling is set for all plots +in the chart to a y-range defined by \f(CW<ymin>\fP and \f(CW<ymax>\fP. +Otherwise the +vertical axis will be autoscaled based on the values currently being +plotted. +.PP +\f(CW<onoff>\fP is one of the keywords \f(CBon\fP or \f(CBoff\fP and the +\f(CBlegend\fP clause controls the presence or absence of the plot +legend below the graph area. The default is for the legend to be shown. +After the view is loaded, the legend visibility +can be toggled using the +.I "Show Legend" +button in the +.I "Edit\(->Chart" +dialog. +.RE +.IP 5. 0.3i +.B pmchart +supports a \f(CBglobal\fP clause to specify the dimensions of the +top-level window (using the \f(CBwidth\fP and \f(CBheight\fP keywords), +the number of visible points (\f(CBpoints\fP keyword) and the starting +X and Y axis positions on the screen (\f(CBxpos\fP and \f(CBypos\fP +keywords). +Each of these \f(CBglobal\fP attributes takes an integer value as the +sole qualifier. +.IP 6. 0.3i +Each \f(CBchart\fP has one or more plots associated with it, as +defined by one of the following specifications: +.ES +\f(CBplot\fP + [\f(CBlegend\fP <title>] [\f(CBcolor\fP <colorspec>] [\f(CBhost\fP <hostspec>] + \f(CBmetric\fP <metricname> + [ \f(CBinstance\fP <inst> | \f(CBmatching\fP <pat> | \f(CBnot-matching\fP <pat> ] +.EE +.RS +.PP +The keyword \f(CBplot\fP may be replaced with the keyword +\f(CBoptional-plot\fP, in which case if the source of performance data +does not include the specified performance metric and/or instance, +then this plot is silently dropped from the chart. +.PP +If specified, the title will appear in the chart legend. +The \f(CW<title>\fP is usually enclosed in quotes (") and it may +contain one or more wildcard characters which will be expanded +using metric name, instance name, and host name for the plot. +The wildcards are "%i" (short unique instance name, up to the first +whitespace), "%I" (full instance name), "%h" (short host name, up +to the first dot), %H (full host name), "%m" (metric name shortened +to the final two PMNS components), and "%M" (full metric name). +.PP +For older +.B pmchart +configuration files, the keyword \f(CBtitle\fP must be used instead of +\f(CBlegend\fP. +Nowadays +.B pmchart +supports either keyword. +.PP +The \f(CBcolor\fP clause is optional for newer +.B pmchart +configuration files, but it was mandatory in the original +.B pmchart +configuration file format. +\f(CW<colorspec>\fP may be one of the following: +.ES +\f(CB#\-cycle\fP +\f(CBrgbi:\fPrr\f(CB:\fPgg\f(CB:\fPbb +\f(CB#\fPrgb +\f(CB#\fPrrggbb +\f(CB#\fPrrrgggbbb +\f(CB#\fPrrrrggggbbbb +<Xcolor> +.EE +where each of \f(CWr\fP, \f(CWg\fP and \f(CWb\fP are hexidecimal +digits (0-9 and A-F) representing respectively the red, green and +blue color components. +\f(CW<Xcolor>\fP is one of the color names from the X color database, +e.g. \f(CBred\fP or \f(CBsteelblue\fP, see also the output from +.BR showrgb (1). +.PP +The "color" \f(CB#\-cycle\fP specifies that +.B pmchart +should use the next in a pallet of colors that it uses cyclically +for each chart. This is the default if the \f(CBcolor\fP clause +is omitted. +.PP +The \f(CW<hostspec>\fP in the \f(CBhost\fP clause may be a hostname, +an IP address or an asterisk (*); the latter is used to mean the +default source of performance metrics. +For older +.B pmchart +configuration files, the \f(CBhost\fP clause must be present, for new +.B pmchart +configuration files it is optional, and if missing the default source +of performance metrics will be used. +.PP +The optional instance specification, +.IP (a) 0.3i +is omitted in which case one plot will be created for every instance of +the \f(CW<metricname>\fP metric +.IP (b) 0.3i +starts with \f(CBinstance\fP, in which case only the instance +named \f(CW<inst>\fP will be plotted +.IP (c) 0.3i +starts with \f(CBmatching\fP, in which case all instances whose +names match the pattern \f(CW<pat>\fP will be plotted; the pattern +uses extended regular expression notation in the style of +.BR egrep (1) +(refer to the PMCD view for an example) +.IP (d) 0.3i +starts with \f(CBnot-matching\fP, in which case all instances whose +names +.B do " " not +match the pattern \f(CW<pat>\fP will be plotted; the pattern +uses extended regular expression notation in the style of +.BR egrep (1) +(refer to the Netbytes view for an example) +.PP +.B pmchart +uses a bizarre syntactic notation where \f(CW<inst>\fP and +\f(CW<pat>\fP extend from the first non-white space character to the +end of the input line. For +.B pmchart +configuration files these elements are either delimited by white +space, or enclosed in quotes ("). +.RE +.IP 7. 0.3i +The optional \f(CBtab\fP directive can be used to create views with +multiple charts which span multiple Tabs. The syntax is as follows: +.ES +\f(CBtab\fP <label> [\f(CBhost\fP <host>] [\f(CBpoints\fP <points> [\f(CBsamples\fP <samples>]] +.EE +.RS +.ES +.PP +All chart specifications following this keyword will be created +on the new Tab, until the end of the configuration file or until +another \f(CBtab\fP keyword is encountered. +.SH "PCP ENVIRONMENT" +Environment variables with the prefix +.B PCP_ +are used to parameterize the file and directory names +used by PCP. +On each installation, the file +.I /etc/pcp.conf +contains the local values for these variables. +The +.B $PCP_CONF +variable may be used to specify an alternative +configuration file, +as described in +.BR pcp.conf (4). +.PP +Of particular note, the +.B $PCP_XCONFIRM_PROG +setting is explicitly and unconditionally overridden by +.B pmchart. +This is set to the +.BR pmconfirm (1), +utility, in order that some popup dialogs (particularly in the +area of Recording) maintain a consistent look-and-feel with the +rest of the +.B pmchart +application. +.SH SEE ALSO +.BR pmtime (1), +.BR pmconfirm (1), +.BR pmdumptext (1), +.BR PCPIntro (1), +.BR pmafm (1), +.BR pmval (1), +.BR pmcd (1), +.BR pminfo (1), +.BR pcp.conf (4), +.BR pcp.env (4) +and +.BR pmns (4). -- cgit v1.2.3