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.
SEE ALSO
mkfifo(1), stdin(4), fd(4), /usr/share/doc/trend/examples/
AUTHORS
trend is distributed under LGPL (see COPYING) WITHOUT ANY WARRANTY. Copyright(c) 2003-2009 by Yuri D’Elia <wavexx [AT] thregr.org>.
November 2, 2007