Ubuntu Manpage: trend — a general-purpose, efficient trend graph

NAME

       trend — a general-purpose, efficient trend graph

SYNOPSIS

       trend     [-dDSsvlmFgGhtAERIMNTLzfcpue]     [-display]     [-geometry]     [-iconic]     ⟨fifo    |    -⟩
             ⟨hist-spec | hist-sz x-sz⟩ [low high]

DESCRIPTION

       trend is a general-purpose, efficient trend graph for "live" data. Data is read in ASCII form from a file
       or continuously from a FIFO and displayed  in  real-time  into  a  multi-pass  trend  (much  like  a  CRT
       oscilloscope).   trend  can  be  used  as a rapid analysis tool for progressive or time-based data series
       together with trivial scripting.

       trend requires at least a valid fifo to read from  and  an  history  specification  (hist-spec)  or,  for
       advanced  usage,  a  combination  of  history  size  and horizontal size (hist-sz and x-sz respectively).
       Optionally, to disable auto-scaling, the vertical limits can be specified directly  through  the  command
       line  via  low and high.  The default input format is ASCII, in absolute counting mode. Many settings can
       be changed directly during execution.

INPUT

FIFO
To display real-time data you should use a FIFO. Both standard input and named pipes can be used.
Standard input (used for simple pipelining purposes) can be opened by using - instead of a named file. A
named FIFO can be created using the mkfifo(1) command. FIFOs are automatically re-opened upon EOF. See
the “EXAMPLES” section.

Alternatively you can store your data in a plain file and simply display its last values non-
interactively.

When new data is written, the value is plotted and the cursor position is advanced. That is, the graph
scrolling speed is determined by the speed of the data flow. When the number of received values is above
the specified horizontal size, the graph will wrap or scroll, depending on your settings.

ASCII DATA
The default data format is a space/tab/newline-separated series of parseable ASCII numbers; eg:

1 2 3 4 5.1 0642
0x12 -12.4E5 .987

The parser is very lenient, and will silently ignore whatever looks like garbage.

COUNTING MODES
By default all input values are considered absolute and displayed "as is" in a single graph.

The -c [N]mode flag sets an alternate counting mode and the number of available graphs. Available modes
are:

a absolute (default)
i incremental counter
d differential values

In incremental and differential mode, each value is calculated using the previous value as a reference
except for the first, which is taken as absolute. The number of graphs can be specified by prefixing a
multiplier before the counting mode (eg: 2a draws two graphs in absolute mode). See “MULTIPLE GRAPHS” for
more details on how this affects the input stream.

FORMAT TYPES
Different input formats are supported, as specified by the -f flag. Note however that only the ASCII
parser (the default) silently ignores errors. NaNs and Infinity have special treatment. Internally, trend
always works with double precision floating points: conversion toward these is performed with the default
FPU conversion rules. The actual underlying binary format depends on the host architecture:

a ASCII parser (default)
f binary float
d binary double
s binary short
i binary int
l binary long

SPECIAL VALUES
ASCII and binary floating point input have special treatment for NaNs and Infinity (entered in any
representable form). Both are considered as "undefined values". Undefined values can be highlighted, but
aren't otherwise rendered. If the -e flag is set, Infinity enters an escape sequence instead (See “ESCAPE
SEQUENCES”)

MULTIPLE GRAPHS
Multiple graphs can be displayed inside a single trend instance by specifying a prefix number N for the
-c flag. The input is interleaved, but otherwise unchanged: the reference value, if needed, is expected
to be seen N times, one for each graph. Thus, for three graphs (A, B and C), the input order is:

[A0 B0 C0]
A1 B1 C1
A2 B2 C2
.. .. ..

The display is updated only once all graph values are read. The color, label and origin for each graph
can be specified through the usual command-line flags, separating each value with a comma; in the same
order as the input. Default colors and labels are assigned if not completely specified.

All graphs share and are affected by the same settings, except for the origin (zero) which can be changed
independently. Filling, values and the examiners only work on the current graph. The current graph can be
cycled dynamically with the TAB key and differentiated using the K key, which cycles between "normal",
"dim others" and "hide others" views. The graph key, if enabled, also highlights the current graph.

ESCAPE SEQUENCES
If escape sequences are enabled (through the -e flag), entering Infinity (in any representable form) will
start an escape sequence. Currently, this feature is not yet implemented: Infinity is simply discarded.
This is reserved for future use as a way to control the trend interface and parameters remotely.

OPTIONS

   FLAGS
       -d                       "dimmed" shading mode
       -D                       visible distribution graph
       -S                       enable anti-aliasing
       -s                       "scrolling" mode
       -v                       visible values
       -l                       visible visual/max sync latency
       -m                       visible marker
       -F                       enable filling
       -g                       visible grid
       -G grid-spec             specify grid resolution
       -z zero[,zero...]        specify y zero/s
       -h                       help and version info
       -t str                   specify a window title
       -A colour                background colour
       -E colour                text (values) colour
       -R colour                grid colour
       -I colour[,colour...]    trend colour/s
       -M colour                marker colour
       -N colour                interactive examiner colour
       -T colour                edit mode colour
       -L label[,label...]      trend label/s
       -c mode                  input number/counting mode (See “COUNTING MODES”)
       -f format                input format (See “FORMAT TYPES”)
       -p rate                  polling rate (hz)
       -u                       show undefined values
       -e                       enable escape sequences (See “ESCAPE SEQUENCES”)
       -display                 See X(7).
       -geometry                See X(7).
       -iconic                  See X(7).

   HIST-SPEC
       An history specification is another convenient form of defining the pair `hist-sz x-sz` for common cases.
       An history specification can be in either one of the following formats:

             N      Sets x-sz to N, and hist-sz to N+1.
             N/M    Sets hist-sz to N, and x-sz to N/M.
             NxM    Sets x-sz to N, and hist-sz to N*M.

       While this may seem hard at first, trend fifo '60x3' is an easier way of expressing  "60  seconds  for  3
       minutes" and similar idioms.

   COLOUR
       A colour is specified in hex RGB format, as follows: #RRGGBB, RRGGBB or 0xRRGGBB; some examples:

             #FF0000    red
             #00FF00    green
             #A020F0    purple

   GRID-SPEC
       A grid specification is of the form:

             [[A][+C]][x[B][+C]]

       (eg: 1.3, 10+5, 1x10+5, +5x+5; +1x+1 gets the old behaviour) where:

             A    y grid resolution
             B    x grid resolution
             C    draw a mayor line every C normal grid lines

DISPLAY

INTERACTIVE KEYS
ESC quit/exit
TAB cycle current graph
a toggle auto-scaling
A re-scale the graph without activating auto-scaling
d toggle dimmed shading mode
D toggle distribution graph
S toggle anti-aliasing
s switch scrolling mode (wrap-around or scrolling)
v toggle values
l show visual and maximal sync latency
L set limits interactively
m activate a marker on the current cursor position
f toggle filling
g toggle grid
G change grid-spec interactively
z change zero interactively
Z set limits by center and amplitude
p change polling rate interactively
u toggle display of undefined values
k toggle the graph key
K cycle view mode (normal, dim others or hide others)
space pause visualisation (but still continue to consume input to preserve time coherency)

AUTOSCALING
When autoscaling is enabled the graph will be scaled vertically to fit visible values. The grid
resolution is used to add some vertical bounds to the graph. Disabling autoscaling interactively will
retain current limits. When the grid is too dense to be displayed it's deactivated automatically.

LATENCY INDICATOR
The latency indicator shows a 5s average of the visual and maximal sync latency (in seconds). The visual
latency is the time-frame between real value updates and the final output you're seeing: it includes
copy/redraw times, which varies depending on enabled layers, plus video sync. The maximal sync latency is
the maximal time ever required for any received value to be synced with the display: since the display is
updated atomically, values received while redrawing are implicitly delayed. See the “UPDATE POLICY”
section for further details.

SHADING MODES
The default is to shade uniformly old values to complete transparency. The "dimmed" shading mode draws
the foreground values with full opacity and the others with half opacity.

SCROLLING MODES
The default visualisation mode is "wrap-around": newer values will simply wrap around the screen when new
data arrives. The other available one is "scrolling": new data is always placed at the right edge of the
screen, and older values scrolled on the left.

VALUE INDICATORS
Three value indicators are drawn on the screen: upper limit, lower limit and current value (respectively
on the upper right, lower right and lower left of the screen).

INTERACTIVE EXAMINERS
You can query interactively the graph for any value in the history by clicking with the first mouse
button. This will enable a permanent examiner in the selected position and display up to the three
nearest values in the upper-left corner of the screen. Intersections are projected horizontally, while a
small circle will show the position of the nearest sampled value. The mean value refers to the three
intersections.

By holding down the CTRL key while clicking/dragging only "foreground" values will be considered.

When clicking inside the distribution graph, the current count for the selected value is displayed
instead.

The examiners can be removed by clicking anywhere with the third mouse button.

DISTRIBUTION GRAPH
D or -D enable a distribution graph on the left side of the window. This is especially useful when
analyzing the continuity of a function or signal. Intensity is proportional to the visible maximum.

FILLING
f or -F enable filling. In standard mode, or when hist-sz is smaller than x-sz, the area between the
curve and zero will be filled. Otherwise, in dimmed mode, the area between the "foreground" and
"background" values is filled instead.

UPDATE POLICY

       The  fifo  is  read  and  managed  asynchronously  from  the graphics. Delays at the display end will not
       interfere with the data feed.

       The fifo is unbuffered and the feeder thread is synchronously locked on it waiting for new data.

       The value is put in the history buffer when a separator character is received after the  value,  or,  for
       binary input, when the needed amount of bytes is read (in this case each value is read with a single read
       call).

       The  polling  rate  (as  defined  by p or -p and defaulting to 1000) defines how often the history buffer
       should be checked for updates and kept in sync with the  visual.  Values  greater  than  1000  result  in
       continuous  scanning  (note  that  this  only affects the maximal sync latency, and not the display rate,
       which is handled automatically).

       Syncing occurs atomically, reflecting the actual state at the instant of the update. Scheduler  latencies
       apply.

ENVIRONMENT

       DISPLAY See X(7).

EXAMPLES

       Running trend with a named FIFO:

             mkfifo fifo
             command > fifo &
             trend fifo ...

       Display the number of current active processes over time:

             (while true; do ps -A | wc -l; sleep 1; done) | \
             trend - 60x24

       Display two graphs:

             trend -c2a -L"graph 1, graph 2" fifo ...

DIAGNOSTICS

       The trend utility exits 0 on success, and >0 if an error occurs.

ERRORS

       trend:  producer thread exiting  The data stream finished for some reason (the specified file was invalid
       at the time of the request). For regular or invalid files this warning is normal.

AUTHORS

       trend is distributed under LGPL (see COPYING) WITHOUT  ANY  WARRANTY.   Copyright(c)  2003-2009  by  Yuri
       D'Elia <wavexx@thregr.org>.

                                                November 2, 2007                                        TREND(1)