Unix/Linux Go Back    


CentOS 7.0 - man page for pmchart (centos section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


PMCHART(1)									       PMCHART(1)

NAME
       pmchart - strip chart tool for Performance Co-Pilot

SYNOPSIS
       pmchart	[-CVWz]  [-A align] [-a archive] [-c configfile] [-g geometry] [-h host] [-o out-
       file] [-O offset] [-p port] [-s samples] [-S starttime] [-T  endtime]  [-t  interval]  [-v
       visible] [-Z timezone] [sources...]

DESCRIPTION
       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 simultane-
       ously,  either  aligned on the unified time axis (X-axis), and through the use of multiple
       interface Tabs.

       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 PCPIntro(1) for
       an in-depth discussion of the capabilities of the PCP framework, many of which are used by
       pmchart.

       Many aspects of the behaviour of pmchart can be customised through the interface.  In par-
       ticular, 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 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.

       pmchart makes extensive use of the pmtime(1) utility for time control, refer to the pmtime
       manual page for further details of its operation.

       Options	which  control the default source, timing and layout of the pmchart window are as
       follows:

       -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 -a options can be presented, and the  list  of
	    archives  is used for sourcing metric values.  Any sources listed on the command line
	    are assumed to be archives if this option is used.

       -c   configfile specifies an initial view to load, using the default  source  of  metrics.
	    Multiple  -c  views  can be specified, and they will all be opened in the default Tab
	    with the default source of metrics.

       -C   Used with -c, the view(s) are parsed, any errors are reported, and	the  tool  exits.
	    This is primarily intended for testing purposes.  If a second -C option is presented,
	    pmchart also connects to pmcd(1) to check the semantics of metrics.

       -g   Generate image with the specified geometry (width and height).  This option  is  only
	    useful  when  used	in conjunction with the -o option for generating an output image.
	    The geometry argument takes the form "WxH" (e.g. 240x120).

       -h   Current performance metric values are retrieved from the nominated	host  machine  by
	    default.   Multiple  -h  options  can be presented, and the list of hosts is used for
	    sourcing metric values.  Any sources listed on the command line  are  assumed  to  be
	    hosts if this option is used.

       -o   Generate  an  image  file named 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 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.

       -p   port number for connection to an existing pmtime time control process.

       -s   Specifies the number of 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.

       -t   Sets the inital update interval to something other than the default  1  second.   The
	    interval  argument	follows  the syntax described in PCPIntro(1), and in the simplest
	    form may be an unsigned integer (the implied units in this case are seconds).

       -v   Sets the inital visible 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 -s value).

       -V   Display pmchart version number and exit

       -W   Export images using an opaque(white) background

       -Z   By default, pmtime reports the time of day according to the  local	timezone  on  the
	    system  where  pmchart is run.  The -Z option changes the timezone to timezone in the
	    format of the environment variable TZ as described in environ(5).

       -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 -h or -a options.

       The  -S, -T, -O and -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 PCPIntro(1) for a complete description of these options.

VIEWS
       The primary 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.

       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  manipu-
       lated.

       The  first  class,  the "system" view, is simply any view that is installed as part of the
       pmchart package.  These are stored in $PCP_VAR_DIR/config/pmchart.   When  the  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  suit-
       able priviledges, as they will be overwritten during an upgrade.

       The second class of view is the "user" view.  These views are created on-the-fly using the
       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 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 $HOME/.pcp/pmchart.

TABS
       pmchart provides the common user interface concept of the Tab, which is most prevalent  in
       modern  web  browsers.	Tabs  allow 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 click-
       ing on the Tab labels, which are located along the top of the display beneath the Menu and
       Tool bars).

       Each  Tab has a mode of operation (either live or archive - 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 pmchart window.  New Tabs can be
       created using the File->Add Tab dialog.

       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 File->Close Tab menu, which removes the  current
       Tab and any charts it contained.

IMAGES and PRINTING
       A  static copy of the currently displayed vertical series of charts can be captured in two
       ways.

       When the intended display device is the screen, the 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.

       Alternatively, when the intended display device is paper, the 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  addi-
       tion  allows printing to the intermediate printer formats of PostScript and Portable Docu-
       ment Format (PDF).

RECORDING
       It is possible to make a recording of a	set  of  displayed  charts,  for  later  playback
       through	pmchart  or any of the other Performance Co-Pilot tools.  The Record->Start func-
       tionality is simple to configure through the user interface, and allows fine-tuning of the
       recording  process  (including record frequencies that differ to the pmchart update inter-
       val, alternate file locations, etc).

       pmchart produces recordings that are compatible with the PCP  pmafm(1)  replay  mechanism,
       for  later  playback  via  a new instance of pmchart.  In addition, when recording through
       pmchart one can also replay the recording immediately, as on termination of the	recording
       (through  the  Record->Stop  menu item), an archive mode Tab will be created with the cap-
       tured view.

       Once recording is active in a Live Tab, the Time Control status button in the bottom  left
       corner  of the pmchart window is displayed with a distinctive red dot.  At any time during
       a pmchart recording session, the amount of space used in the filesystem by that	recording
       can be displayed using the Record->Query menu item.

       Finally, the Record->Detach menu option provides a mechanism whereby the recording process
       can be completely divorced from the running pmchart process, and allowed  to  continue  on
       when pmchart exits.  A dialog displaying the current size and estimated rate of growth for
       the recording is presented.  On the other hand, if pmchart is terminated  while	recording
       is  in process, then the recording process will prompt the user to choose immediate cessa-
       tion of recording or for it to continue on independently.

       All of the record mode services available from pmchart are implemented with the assistance
       of  the base Performance Co-Pilot logging services - refer to pmlogger(1) and pmafm(1) for
       an extensive description of the capabilities of these tools.

CONFIGURATION FILE SYNTAX
       pmchart loads predefined chart configurations (or "views") from external files  that  con-
       form  to  the  following  rules.   In  the descriptions below keywords (shown in bold) may
       appear in upper, lower or mixed case, elements shown in [stuff] are  optional,  and  user-
       supplied  elements are shown as <other stuff>.  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.

       1. The first line defines the configuration file type and should be
	       #kmchart
	  although  pmchart  provides  backwards compatibility for the older pmchart view formats
	  with an initial line of
	       #pmchart

       2. 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.

       3. The next line should be
	       version <n> <host-clause>
	  where <n> depends on the configuration file type, and is 1 for pmchart else 1.1, 1.2 or
	  2.0 for pmchart.
	  The <host-clause> part is optional (and ignored) for pmchart configuration  files,  but
	  required for the pmchart configuration files, and is of the form
	       host literal
	  or
	       host dynamic

       4. A configuration contains one or more charts defined as follows:
	       chart [title <title>] style <style> <options>
	  If specified, the title will appear centred and above the graph area of the chart.  The
	  <title> 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.  After the view is loaded,  the  title  visibility  and
	  setting can be manipulated using the Chart Title text box in the Edit->Chart dialog.

	  The  <style> controls the initial plotting style of the chart, and should be one of the
	  keywords plot (line graph), bar, stacking (stacked bar), area  or  utilization.   After
	  the view is loaded, the plotting style can be changed using the Edit->Chart Style drop-
	  down list.

	  The <options> are zero or more of the optional elements:
	       [scale [from] <ymin> [to] <ymax>] [legend <onoff>]
	  If scale is specfied, the vertical scaling is set for all plots in the chart	to  a  y-
	  range  defined  by  <ymin>  and <ymax>.  Otherwise the vertical axis will be autoscaled
	  based on the values currently being plotted.

	  <onoff> is one of the keywords on or off and the legend 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  Show
	  Legend button in the Edit->Chart dialog.

       5. pmchart  supports  a	global	clause	to specify the dimensions of the top-level window
	  (using the width and height keywords), the number of visible	points	(points  keyword)
	  and  the  starting X and Y axis positions on the screen (xpos and ypos keywords).  Each
	  of these global attributes takes an integer value as the sole qualifier.

       6. Each chart has one or more plots associated with it, as defined by one of the following
	  specifications:
	       plot
		   [legend <title>] [color <colorspec>] [host <hostspec>]
		   metric <metricname>
		   [ instance <inst> | matching <pat> | not-matching <pat> ]

	  The  keyword	plot may be replaced with the keyword optional-plot, 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.

	  If  specified,  the  title  will  appear  in	the chart legend.  The <title> is usually
	  enclosed in quotes (") and if it contains the sequence "%i" this will  be  replaced  by
	  the metric instance name (if any).

	  For  older  pmchart configuration files, the keyword title must be used instead of leg-
	  end.	Nowadays pmchart supports either keyword.

	  The color clause is optional for newer pmchart configuration files, but it  was  manda-
	  tory	in the original pmchart configuration file format.  <colorspec> may be one of the
	  following:
	       #-cycle
	       rgbi:rr:gg:bb
	       #rgb
	       #rrggbb
	       #rrrgggbbb
	       #rrrrggggbbbb
	       <Xcolor>
	  where each of r, g and b are hexidecimal digits (0-9 and A-F) representing respectively
	  the  red, green and blue color components.  <Xcolor> is one of the color names from the
	  X color database, e.g. red or steelblue, see also the output from showrgb(1).

	  The "color" #-cycle specifies that pmchart should use the next in a  pallet  of  colors
	  that	it  uses  cyclically  for each chart.  This is the default if the color clause is
	  omitted.

	  The <hostspec> in the host 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
	  pmchart configuration files, the host clause must be present, for new pmchart  configu-
	  ration  files  it is optional, and if missing the default source of performance metrics
	  will be used.

	  The optional instance specification,

	  (a)
	     is omitted in which case one plot will be created for every instance of the <metric-
	     name> metric

	  (b)
	     starts with instance, in which case only the instance named <inst> will be plotted

	  (c)
	     starts  with  matching,  in  which  case all instances whose names match the pattern
	     <pat> will be plotted; the pattern uses extended regular expression notation in  the
	     style of egrep(1) (refer to the PMCD view for an example)

	  (d)
	     starts with not-matching, in which case all instances whose names do   not match the
	     pattern <pat> will be plotted; the pattern uses extended regular expression notation
	     in the style of egrep(1) (refer to the Netbytes view for an example)

	  pmchart  uses a bizarre syntactic notation where <inst> and <pat> extend from the first
	  non-white space character to the end of the  input  line.   For  pmchart  configuration
	  files these elements are either delimited by white space, or enclosed in quotes (").

       7. The  optional tab directive can be used to create views with multiple charts which span
	  multiple Tabs.  The syntax is as follows:
	       tab <label> [host <host>] [points <points> [samples <samples>]]

	  All chart specifications following this keyword will be created
	  on the new Tab, until the end of the configuration file or until
	  another tab keyword is encountered.

PCP ENVIRONMENT
       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 config-
       uration file, as described in pcp.conf(4).

       Of particular note, the $PCP_XCONFIRM_PROG setting is explicitly and unconditionally over-
       ridden by pmchart.  This is set to the 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 pmchart application.

SEE ALSO
       pmtime(1),  pmconfirm(1),  pmdumptext(1),  PCPIntro(1),	 pmafm(1),   pmval(1),	 pmcd(1),
       pminfo(1), pcp.conf(4), pcp.env(4) and pmns(4).

Performance Co-Pilot								       PMCHART(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:07 AM.