UTH

UTH is a simple utility for creating time histogram plots, based on the JAS plotting widget. It is designed to read its input from a OS dependent command, such as ping or iostat.  UTH can be configured using an XML configuration file.

UTH is written in Java so should run on any platform which supports Java.

This is an example configuration file:

<UTHPlotter x="10%" y="10%" width="50%" height="40%" title="Ping Plot">
  <label axis="x">Time (seconds)</label>
  <label axis="y">Ping (ms)</label>
  <axis position="y" min="1" max="1000" logarithmic="true"/>
  <command command="ping -t www.cern.ch">
    <re match="time(.*)ms" fail="timed out">
      <data color="blue" symbol="none" bins="120">
        <legend>www.cern.ch</legend>
      </data>
    </re>
  </command>
  <command command="ping -t www.slac.stanford.edu">
    <re match="time(.*)ms" fail="timed out">
      <data color="green" symbol="circle" size="2">
         <legend>www.slac.stanford.edu</legend>
      </data>
    </re>
  </command>
</UTHPlotter>

Configuration File Syntax

• UTHPlotter tag
• label tag
• axis tag
• command tag
• re tag
• data tag
• legend tag

UTHPlotter tag

Must be the first tag in the XML file.

Attributes:

• x The x position for the window. May be absolute (pixels) or a % of screen width.
• y The y position for the window. May be absolute (pixels) or a % of screen height.
• width The width for the window. May be absolute (pixels) or a % of screen width.
• height The height for the window. May be absolute (pixels) or a % of screen height.
• title The title to be associated with the window.
• foreground The foreground color for the window
• background The background color for the window
• showLegend One of true, false or auto (the default -- means show if >1 data series)

Contained Tags:

• label, axis, command

label tag

Defines an axis label

Attributes:

• axis The axis to which this label should be attached, either x or y

Contained Tags:

• none

Text:

• The text of the label.

axis tag

Defines attributes for an axis

Attributes:

• position Either x or y
• logarithmic If true the axis should be logarithmic (Y axis only). Note - currently you must specify min, max if you set logarithmic=true, this is a bug which should be fixed in a future release.
• min The minimum value to be displayed on the axis (Y axis only).
• max The maximum value to be displayed on the axis (Y axis only).
• forceZero Force zero to be on the axis (Y axis only).
• showTime Show absolute time instead of time relative to now (X axis only).
• bins The number of bins on the X axis (default 60) (X axis only)
• range The time range on the X axis (default = bins) (X axis only)

Contained Tags:

• none

command tag

Specify a command from which data will be read. Each command tag should contain one or more re tags, used to extract information from the command output and generate a plot.

Attributes:

• command The command to be issued.

Contained Tags:

• re

re tag

Used to specify a regular expression which will be used to extract information from the output of a command.

Attributes:

• match A regular expression which results in a "match". Each time a line of output matches this expression a new entry will be made in the plot. The regular expression should contain one or more sub-expressions in parentheses which will be used to extract values to be plotted.
• fail A regular expression which results in a failure. Each time a line of output matches this expression a missing point entry will be made in the plot.

Contained Tags:

• data

data tag

Defines a data series. Each regular expression (re tag) should have one or more data series associated with it.

Attributes:

• color The color to be used for these data series
• symbol The plot symbol to be used, one of (none,box,circle,cross,diamond,dot,horiz line,square,star,triangle,vert line)
• size The symbol size in pixels
• line One of true (default) or false, indicating of a line should be drawn between points.
• delta If true then the difference between the old and new value will be plotted.
• value The index of the sub-expression that will be used to define the value (default 1)

Contained Tags:

• legend

legend tag

Defines the text to be used in the legend for a particular data series.

Attributes:

• none

Contained Tags:

• none

Text:

• The text to be inserted in the legend.

How to specify colors

You can specify colors using common names, e.g. blue, red, green etc, or as RGB values using the syntax (rrr,ggg,bbb) where rrr etc =0 to 255.

Download

The latest version is 0.1.2, downloadable from here.

Feedback

Please send feedback/suggestions/bugs/complaints to tonyj@slac.stanford.edu.