File: aprx-stat.8.in

package info (click to toggle)
aprx 2.9.0+dfsg-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 2,352 kB
  • sloc: ansic: 15,809; sh: 598; makefile: 160
file content (216 lines) | stat: -rw-r--r-- 5,879 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
.TH aprx\-stat 8 "@DATEVERSION@"
.SH NAME
.B aprx\-stat
\- statistics utility for
.BR aprx (8)
.SH SYNOPSIS
.B aprx\-stat
.RB [ \-t ]
.RB [ \-f \fI@VARRUN@/aprx.state\fR]
.RB { \-S | \-x | \-X }
.SH DESCRIPTION
.B aprx\-stat
is a statistics utility for
.BR aprx (8)
program.

.SH OPTIONS
The
.B aprx\-stat
has following runtime options:
.TP
.B "\-f \fI@VARRUN@/aprx.state\fR"
Turn on verbose debugging, outputs data to STDOUT.
.TP
.B "\-S"
SNMP data mode, current counter and gauge values.
.TP
.B "\-t"
Use UNIX
.I time_t
for timestamps, instead of human readable text format.
.TP
.B "\-x"
Lattest of extended historical gauge values.
This gives for each input interface
.RS
.IP \(bu 2
SNMP data
.IP \(bu 2
last 90 of 1 minute values,
.IP \(bu 2
10 of 10 minute values,
.IP \(bu 2
3 of 60 minute values.
.RE
.TP
.B "\-X"
Full extended historical gauge values.
This gives all the contents of historical value data ring-buffers.
.RS
.IP \(bu 2
SNMP data
.IP \(bu 2
1 minute resolution: 24 hours
.IP \(bu 2
10 minute resolution: 7 days
.IP \(bu 2
60 minute resolution: 3 months
.RE

.SH SNMP DATA OUTPUT
For each interface feeding AX.25 packets and/or KISS frames to this program,
there are following kind of 
.nf
\fC
SNMP  /dev/ttyUSB1   798282 11088   0  0     3
SNMP  ax0   798282 11088   0  0     7
SNMP  ax1   798282 11088   0  0     94
.fi
.PP
where columns are:
.IP \(bu 2
"SNMP" - keyword
.IP \(bu 2
Interface (AX.25 IF name, or serial port device name)
.IP \(bu 2
Received byte counter
.IP \(bu 2
Received frame (packet) counter
.IP \(bu 2
.\" Transmitted byte counter (will stay zero)
.I Dropped
byte counter
.IP \(bu 2
.\" Transmitted frame counter (will stay zero)
.I Dropped
frame counter
.IP \(bu 2
Age in seconds of last update of this statistics.

.SH EXTENDED DATA OUTPUT
Extended data output gives formatted historical periodic accumulates of interface traffic
counters, and Erlang value estimates based on that.
.PP
.nf
\fC

SNMP  /dev/ttyUSB1   816675 11332   0  0     15

1min data
2007-12-24 14:10  /dev/ttyUSB1  1m    374    6      0    0   0.047  0.000
2007-12-24 14:09  /dev/ttyUSB1  1m    377    5      0    0   0.047  0.000
2007-12-24 14:08  /dev/ttyUSB1  1m    347    5      0    0   0.043  0.000
2007-12-24 14:07  /dev/ttyUSB1  1m    140    2      0    0   0.018  0.000
\(bu\(bu\(bu

10min data
2007-12-24 14:10  /dev/ttyUSB1 10m   3829   55      0    0   0.048  0.000
2007-12-24 14:00  /dev/ttyUSB1 10m   2182   28      0    0   0.027  0.000
2007-12-24 13:50  /dev/ttyUSB1 10m   3205   44      0    0   0.040  0.000
2007-12-24 13:40  /dev/ttyUSB1 10m   3811   50      0    0   0.048  0.000
\(bu\(bu\(bu

60min data
2007-12-24 14:00  /dev/ttyUSB1 60m  22510  295      0    0   0.047  0.000
2007-12-24 13:00  /dev/ttyUSB1 60m  24886  347      0    0   0.052  0.000
\(bu\(bu\(bu
.fi
.PP
The output repeats for all interfaces.
.PP
The SNMP dataset is given in the beginning, and described above.
Then each extended output line has following fields:
.IP \(bu 2
Timestamp is two fields, date and time (in minute resolution) is in UTC.
.IP \(bu 2
Alternate timestamp format is UNIX
.I time_t
as an integer, counting seconds from epoch, and as single field.
.IP \(bu 2
Interface name is same as in SNMP case.
.IP \(bu 2
Data qualifier tells what integration period the data is valid for:
.IR 1m ", " 10m ", " 60m .
.IP \(bu 2
Counter of received bytes on interface (including KISS flags etc.)
.IP \(bu 2
Counter of received frames.
.IP \(bu 2
.\" Counter of transmitted bytes on interface
Counter of dropped bytes.
.IP \(bu 2
.\" Counter of transmitted frames.
Counter of dropped frames.
.IP \(bu 2
Reception
.I Erlang 
value estimate.
.IP \(bu 2
.\" Transmission
Dropped bytes
.I Erlang
value estimate.
.PP
.SH TODO
.SH BUGS
.SH SEE ALSO
.BR aprx (8)

.SH CONFIGURATION FILE
There is no configuration file.

.SH NOTES: ERLANG
The
.I Erlang
is telecom measurement of channel occupancy, and in this application sense
it does tell how much traffic there is on the radio channel.
.PP
Most radio transmitters are not aware of all transmitters on channel,
and thus there can happen a collision causing loss of both messages.
The higher the channel activity, the more likely that collision is.
For further details, refer to statistical mathematics books, or perhaps
on Wikipedia.
.PP
In order to measure channel activity, the
.B aprx
program suite has these built-in statistics counter and summary estimators.
.PP
The
.I Erlag
value that the estimators present are likely somewhat
.I underestimating
the true channel occupancy simply because it calculates estimate of channel
bit transmit rate, and thus a per-minute character capacity.
It does not know true frequency of bit-stuffing events of the HDLC framing,
nor each transmitter pre- and port frame PTT times. The transmitters need to
stabilize their transmit oscillators in many cases, which may take up to
around 500 ms!
The counters are not aware of this preamble-, nor postamble-times.
.PP
The HDLC bit stuffing ratio is guessed to be 8.2 bits for each 8 bits of payload.


.SH NOTES: SUID ROOT
This program needs probably to be run as
.I "suid\-root" 
!
It is considered safe to do so, as this checks that the
.B "\-f"
parameter file is of correct "magic value", and will not try to create
it if it does not exist, nor modify that file under any circumstances,
nor reveal content of "wrong magic kind" of file.

.SH AUTHOR
This little piece was written by
.I "Matti Aarnio, OH2MQK"
during a dark and rainy fall and winter of 2007-2008 after a number
of discussions grumbling about current breed of available software
for APRS iGate use in Linux (or of any UNIX) platforms.
Fall and winter 2009-2010 saw appearance of digipeater functionality.
.PP
Principal contributors and test users include:
.IR "Pentti Gronlund, OH3BK" ,
.IR "Reijo Hakala, OH1GWK" .
Debian packaging by
.IR "Kimmo Jukarinen, OH3GNU" .