aprx-stat(8)

✨ aprx-stat 💖

okay bestie, welcome to aprx-stat, the statistics utility that rides along with aprx(8) 💅 this whole page is from the System Manager's Manual, and it's literally just here to spill all the tea about your packet traffic. no cap.

---

🌸 NAME 🌸

aprx-stat — a statistics utility for aprx(8). she counts things. she's iconic for it. 👑

---

🎀 SYNOPSIS 🎀

aprx-stat [-t] [-f/var/run/aprx.state] {-S|-x|-X}

that's the whole vibe. pick your mode, optionally point her at a state file, optionally demand raw UNIX timestamps. periodt. ✨

---

🦋 DESCRIPTION 🦋

aprx-stat is a statistics utility for the aprx(8) program. that's it, that's the description, she's lowkey mysterious like that. 🙈

---

💖 OPTIONS 💖

the aprx-stat has the following runtime options, and you will be reading all of them:

• -f /var/run/aprx.state — turn on verbose debugging and output the data to STDOUT. (yes, the flag is -f and the path is written right up against it in the synopsis, exactly like that, don't come for me.)
• -S — SNMP data mode, giving you the current counter and gauge values. the moment of now, bestie. ⭐
• -t — use UNIX time_t for timestamps instead of the human readable text format. raw numbers, main character energy. 🔥
• -x — the lattest of extended historical gauge values. this gives, for each input interface:
  • SNMP data
  • last 90 of 1 minute values
  • 10 of 10 minute values
  • 3 of 60 minute values
• -X — full extended historical gauge values. this gives all the contents of the historical value data ring-buffers:
  • SNMP data
  • 1 minute resolution: 24 hours
  • 10 minute resolution: 7 days
  • 60 minute resolution: 3 months

lowercase -x = a lil taste. uppercase -X = the whole buffet. 🍓

---

🌈 SNMP DATA OUTPUT 🌈

for each interface feeding AX.25 packets and/or KISS frames to this program, you get lines that look exactly like this:

SNMP  /dev/ttyUSB1   798282 11088   0  0     3
SNMP  ax0   798282 11088   0  0     7
SNMP  ax1   798282 11088   0  0     94

and where columns are, one by one:

• "SNMP" — keyword
• Interface (AX.25 IF name, or serial port device name)
• Received byte counter
• Received frame (packet) counter
• Dropped byte counter
• Dropped frame counter
• Age in seconds of last update of this statistics.

---

✨ EXTENDED DATA OUTPUT ✨

extended data output gives formatted historical periodic accumulates of interface traffic counters, plus Erlang value estimates based on that. it's giving data girlie. 📊

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
•••

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
•••

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
•••

the output repeats for all interfaces. 🔁

the SNMP dataset is given in the beginning, and described above. then each extended output line has the following fields:

• Timestamp is two fields, date and time (in minute resolution) is in UTC.
• Alternate timestamp format is UNIX time_t as an integer, counting seconds from epoch, and as single field.
• Interface name is same as in SNMP case.
• Data qualifier tells what integration period the data is valid for: 1m, 10m, 60m.
• Counter of received bytes on interface (including KISS flags etc.)
• Counter of received frames.
• Counter of dropped bytes.
• Counter of dropped frames.
• Reception Erlang value estimate.
• Dropped bytes Erlang value estimate.

---

💀 TODO 💀

nothing here yet, bestie. the void is the to-do list. 😭

---

🐛 BUGS 🐛

also empty. we're manifesting zero bugs. 🧚

---

🫶 SEE ALSO 🫶

• aprx(8)

---

🌸 CONFIGURATION FILE 🌸

there is no configuration file. she said "I don't need one" and honestly? respect. 🙈

---

💜 NOTES: ERLANG 💜

the Erlang is a telecom measurement of channel occupancy, and in this application sense it does tell how much traffic there is on the radio channel.

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. (she's pointing you at the library, fr fr. 📚)

in order to measure channel activity, the aprx program suite has these built-in statistics counter and summary estimators.

the Erlag value that the estimators present are likely somewhat 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. 💀

the HDLC bit stuffing ratio is guessed to be 8.2 bits for each 8 bits of payload.

okay so important: those numbers are estimates. she's guessing, and she knows she's guessing. don't @ her. 🫶

---

🔥 NOTES: SUID ROOT 🔥

this program needs probably to be run as suid-root! it is considered safe to do so, as this checks that the -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.

read that again, bestie — suid-root is real here, but the rules are strict and she pinky-promises: no creating, no modifying, no leaking. 👑

---

👑 AUTHOR 👑

this little piece was written by 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.

principal contributors and test users include: Pentti Gronlund, OH3BK, Reijo Hakala, OH1GWK. Debian packaging by Kimmo Jukarinen, OH3GNU.

---

that's the whole page, bestie, and we made it to the very end 💖 this one's from the System Manager's Manual, version 2.9.1 of the aprx-stat(8) page — and yeah, the footer really did just say 2.9.1 - with no date, so that's what we're going with. slay, stay hydrated, and go read your counters. 🎀🦋✨