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.
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 allows to specify 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.
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:
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.
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@users.sf.net⟩.