summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDaniel Willmann <dwillmann@sysmocom.de>2019-07-25 17:26:25 +0200
committerDaniel Willmann <dwillmann@sysmocom.de>2019-07-25 17:26:25 +0200
commitabadcd5f8a663695b6c8d0d249806e81116570e7 (patch)
treeed81341592b5e841449e88480e4d8fb387383016
parentc19708bf1ad66f07224e2d99c5d064044db1ddcb (diff)
counters-overview: Add a section about the stats reporter
-rw-r--r--common/chapters/counters-overview.adoc96
1 files changed, 87 insertions, 9 deletions
diff --git a/common/chapters/counters-overview.adoc b/common/chapters/counters-overview.adoc
index fbdef30..8f9a29a 100644
--- a/common/chapters/counters-overview.adoc
+++ b/common/chapters/counters-overview.adoc
@@ -3,7 +3,7 @@
The following gives an overview of all the types of counters available:
-=== Osmo Counters
+=== Osmo Counters (deprecated)
Osmo counters are the oldest type of counters added to Osmocom projects.
They are not grouped.
@@ -26,12 +26,11 @@ The control interface command to get a counter (group) is:
rate_ctr.per_{sec,min,hour,day,abs}.<group_name>.<idx>.[counter_name]
-It is possible to get all counters from a group by omitting the counter name
+It is possible to get all counters in a group by omitting the counter name
=== Stat Item
-Stat items are a grouped replacement for osmo counters, but not many stat
-items are available yet.
+Stat items are a grouped replacement for osmo counters.
* Printed as part of VTY show stats
* Replacement for osmo counters
@@ -39,12 +38,91 @@ items are available yet.
* Grouped and indexed like rate counters
* Items have a unit
* Keeps a list of the last values measured, so could return an average, min,
- max, std. deviation
+ max, std. deviation. So far this is not implemented in any of the reporting
+ options.
-=== Stats Reporter
+=== Statistic Levels
+
+There are three levels on which a statistic can be aggregated in Osmocom
+projects: globally, per-peer and per-subscriber.
+
+==== Global
+
+These are global statistics.
+
+==== Peer
-Statsd stats reporter can send osmo counter, rate counter and stats item values to statsd
+These statistics relate to a peer the program connects to such as the NSVC in
+an SGSN.
-See the stats reporter command of the VTY reference for details on how to
-setup the connection to statsd.
+This level also includes reporting global statistics.
+
+==== Subscriber
+
+These statistics are related to an individual mobile subscriber. An example
+would be bytes transferred in an SGSN PDP context.
+
+This level also includes global and peer-based statistics.
+
+=== Stats Reporter
+The stats reporter periodically collects osmo counter, rate counter and
+stat item values and sends them to a backend. Currently implemented are
+outputting to the configured log targets and a statsd connector.
+
+==== Configuring a stats reporter
+
+Periodically printing the statistics to the log can be done in the following
+way:
+
+.Log statistics
+====
+
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# stats interval 60 <1>
+OsmoBSC(config)# stats reporter log <2>
+OsmoBSC(config-stats)# level global <3>
+OsmoBSC(config-stats)# enable <4>
+----
+====
+
+<1> The interval determines how often the statistics are reported.
+<2> Write the statistic information to any configured log target.
+<3> Report only `global` statistics (can be `global`, `peer`, or
+ `subscriber`).
+<4> Enable the reporter, `disable` will disable it again.
+
+The counter values can also be sent to any aggregation/visualization tool that
+understands the statsd format, for example a statsd server with graphite or
+prometheus using the statsd_exporter together with grafana.
+
+The statsd format is specified in https://github.com/b/statsd_spec
+
+.Report statistics to statsd
+====
+
+----
+OsmoBSC> enable
+OsmoBSC# configure terminal
+OsmoBSC(config)# stats interval 10
+OsmoBSC(config)# stats reporter statsd <1>
+OsmoBSC(config-stats)# prefix BSC1 <2>
+OsmoBSC(config-stats)# level subscriber <3>
+OsmoBSC(config-stats)# remote-ip 1.2.3.4 <4>
+OsmoBSC(config-stats)# remote-port 8125 <5>
+OsmoBSC(config-stats)# enable
+----
+====
+
+<1> Configure the statsd reporter.
+<2> Prefix the reported statistics. This is useful to distinguish statistics
+ from multiple instances of the same service.
+<3> Report only `global` statistics or include `peer` or `subscriber`
+ statistics as well.
+<4> IP address of the statsd server.
+<5> UDP port of the statsd server. Statsd by default listens to port 8125.
+
+Setting up a statsd server and configuring the visualization is beyond the
+scope of this document.