Describe statistics in doc/STATS.md

4 files changed, 36 insertions, 3 deletions

diff --git a/doc/README.md b/doc/README.md
index 111be57..31f6378 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -51,7 +51,7 @@ control interface.
 
 Two scripts are used for monitoring systems: *stats_dabmux_munin.py* for Munin,
 and *retodrs.pl* for Xymon. You can use *show_dabmux_stats.py* to print the
-statistics to console.
+statistics to console. The values are described in *STATS.md*
 
 *DabMux.1* is an old manpage that describes the command line options that
 existed in past versions. It is kept for archive.
diff --git a/doc/STATS.md b/doc/STATS.md
new file mode 100644
index 0000000..385d41e
--- /dev/null
+++ b/doc/STATS.md
@@ -0,0 +1,33 @@
+Stats available through Management Server
+=========================================
+
+Interface
+---------
+
+The management server makes statistics about the inputs available through a ZMQ request/reply socket.
+
+The `show_dabmux_stats.py` illustrates how to access this information.
+
+Meaning of values
+-----------------
+
+`max` and `min` indicate input buffer fullness in bytes.
+
+`under` and `over` count the number of buffer underruns and overruns.
+
+`audio L` and `audio R` show the maximum audio level in dBFS over the last 500ms.
+
+`peak L` and `audio R` show the max audio level in dBFS over the last 5 minutes.
+
+The audio levels are measured in the audio encoder and carried in the EDI
+`ODRa` TAG, or in the ZMQ metadata. Otherwise ODR-DabMux would have to decode
+all audio contributions to measure the audio level.
+
+`State` is either NoData, Unstable, Silence, Streaming.
+Unstable means that underruns or overruns have occurred in the previous 30 minutes.
+Silence means the stream is working, but audio levels are always below -50dBFS.
+
+`version` and `uptime` are fields directly coming from the contribution source,
+and are only supported for the EDI input. These are carried over EDI using custom
+TAG `ODRv` (see function `parse_odr_version_data` in `lib/edi/common.cpp`).
+
diff --git a/doc/advanced.mux b/doc/advanced.mux
index e010150..1034357 100644
--- a/doc/advanced.mux
+++ b/doc/advanced.mux
@@ -40,7 +40,7 @@ general {
     ; statistics data (buffers, overruns, underruns, etc)
     ; which can then be graphed a tool like Munin
     ; The doc/stats_dabmux_multi.py tool is a suitable
-    ; plugin for that.
+    ; plugin for that. The data fields are documented in doc/STATS.md
     ; If the port is zero, or the line commented, the server
     ; is not started.
     managementport 12720
diff --git a/doc/example.mux b/doc/example.mux
index cf02467..3284808 100644
--- a/doc/example.mux
+++ b/doc/example.mux
@@ -61,7 +61,7 @@ general {
     ; statistics data (buffers, overruns, underruns, etc)
     ; which can then be graphed a tool like Munin
     ; The doc/stats_dabmux_multi.py tool is a suitable
-    ; plugin for that.
+    ; plugin for that. The data fields are documented in doc/STATS.md
     ; If the port is zero, or the line commented, the server
     ; is not started.
     managementport 12720