Change in osmo-remsim[master]: manual: Document the logging configuration

This is merely a historical archive of years 2008-2021, before the migration to mailman3.

A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.

laforge gerrit-no-reply at lists.osmocom.org
Thu Dec 9 14:39:42 UTC 2021 

laforge has submitted this change. ( https://gerrit.osmocom.org/c/osmo-remsim/+/26482 )

Change subject: manual: Document the logging configuration
......................................................................

manual: Document the logging configuration

Change-Id: I66f5fe2e55c7e4cb6cc8ce09dcd8a636c717a5a0
---
A doc/manuals/chapters/logging.adoc
M doc/manuals/chapters/remsim-bankd.adoc
M doc/manuals/chapters/remsim-client.adoc
M doc/manuals/chapters/remsim-server.adoc
M doc/manuals/osmo-remsim-usermanual.adoc
5 files changed, 90 insertions(+), 6 deletions(-)

Approvals:
  Jenkins Builder: Verified
  fixeria: Looks good to me, but someone else must approve
  laforge: Looks good to me, approved



diff --git a/doc/manuals/chapters/logging.adoc b/doc/manuals/chapters/logging.adoc
new file mode 100644
index 0000000..bf4ebe5
--- /dev/null
+++ b/doc/manuals/chapters/logging.adoc
@@ -0,0 +1,58 @@
+[[remsim_logging]]
+== osmo-remsim logging
+
+All programs within the osmo-remsim project use the logging sub-system of `libosmocore`.
+
+Contrary to the larger Osmocom projects with their own VTY + configuration file, the
+logging configuration for osmo-remsim programs must happen via command line arguments.
+
+Also, contrary to the larger Osmocom projects, only logging to `stderr` is supported;
+no direct logging to log files, syslog, systemd, etc. is supported at this point.
+
+=== `-d` command line argument
+
+Every osmo-remsim program like `osmo-remsim-bankd`, `osmo-remsim-server` or
+`osmo-remsim-client-st2` supports a `-d` command line argument.  This argument
+takes one mandatory parameter configuring the log level for each log sub-system
+as follows:
+
+`-d SUBSYS,num_lvl[:SUBSYS,num_lvl[:...]]`
+
+So basically, a colon-separated list of tuples, where each tuple contains the
+sub-system name and the _numeric_ log level.
+
+Below is the list of sub-systems and a table of numerical levels:
+
+.libosmocore log levels and their numeric values
+[options="header",width="30%",cols="1,1"]
+|===
+|Level name|Numeric value
+|DEBUG|1
+|INFO|3
+|NOTICE|5
+|ERROR|7
+|FATAL|8
+|===
+
+.osmo-remsim log sub-system names and their description
+[options="header",width="50%",cols="1,2"]
+|===
+|Sub-System Name|Description
+|DMAIN|respective main program code
+|DST2|SIMtrace2 `cardem` firmware interaction via USB
+|DRSPRO|RSPRO protocol between bankd, server and client
+|DREST|REST interface of `osmo-remsim-server`
+|DSLOTMAP|slotmap code shared by `osmo-remsim-server` and `osmo-remsim-bankd`
+|DBANKDW|worker threads of `osmo-remsim-bankd`
+|===
+
+=== Example
+
+Putting the above in a concrete example:
+
+`-d DMAIN,5:DRSPRO,1`
+
+would perform the following configuration:
+
+* log only NOTICE (or higher) messages in the DMAIN subsystem (low verbosity)
+* log DEBUG (or higher) messages in the DRSPRO subsystem (very high verbosity)
diff --git a/doc/manuals/chapters/remsim-bankd.adoc b/doc/manuals/chapters/remsim-bankd.adoc
index ab7a362..da529e2 100644
--- a/doc/manuals/chapters/remsim-bankd.adoc
+++ b/doc/manuals/chapters/remsim-bankd.adoc
@@ -61,12 +61,16 @@
 
 ==== SYNOPSIS
 
-*osmo-remsim-bankd* [-h] [-i A.B.C.D] [-p <1-65535>] [-b <1-65535>] [-n <1-65535>] [-I A.B.C.D] [-P <1-65535> ]
+*osmo-remsim-bankd* [-h] [-V] [-d LOGOPT] [-i A.B.C.D] [-p <1-65535>] [-b <1-65535>] [-n <1-65535>] [-I A.B.C.D] [-P <1-65535> ]
 
 ==== OPTIONS
 
 *-h, --help*::
   Print a short help message about the supported options
+*-V, --version*::
+  Print the software version number
+*-d, --debug LOGOPT*::
+  Configure the logging verbosity, see <<remsim_logging>>.
 *-i, --server-host A.B.C.D*::
   Specify the remote IP address/hostname of the `osmo-remsim-server` to
   which this bankd shall establish its RSPRO control connection
@@ -83,7 +87,7 @@
   Specify the local IP address to which the socket for incoming connections
   from `osmo-remsim-clients` is bound to.
 *-P, --bind-port <1-65535>*::
-  Specify the local TCP port to whicc the socket for incoming connections
+  Specify the local TCP port to which the socket for incoming connections
   from `osmo-remsim-client`s is bound to.
 
 ==== Examples
diff --git a/doc/manuals/chapters/remsim-client.adoc b/doc/manuals/chapters/remsim-client.adoc
index 5e17ec0..f2ee952 100644
--- a/doc/manuals/chapters/remsim-client.adoc
+++ b/doc/manuals/chapters/remsim-client.adoc
@@ -72,7 +72,11 @@
 
 *-h, --help*::
   Print a short help message about the supported options
-*-s, --server-host A.B.C.D*::
+*-V, --version*::
+  Print the software version number
+*-d, --debug LOGOPT*::
+  Configure the logging verbosity, see <<remsim_logging>>.
+*-i, --server-ip A.B.C.D*::
   Specify the remote IP address / hostname of the `osmo-remsim-server` to
   which this client shall establish its RSPRO control connection
 *-p, --server-port <1-65535>*::
@@ -220,6 +224,8 @@
   Print a short help message about the supported options
 *-v, --version*::
   Print the compile-time version information
+*-d, --debug LOGOPT*::
+  Configure the logging verbosity, see <<remsim_logging>>.
 *-i, --server-ip A.B.C.D*::
   Specify the remote IP address / hostname of the `osmo-remsim-server` to
   which this client shall establish its RSPRO control connection
diff --git a/doc/manuals/chapters/remsim-server.adoc b/doc/manuals/chapters/remsim-server.adoc
index 304a7f3..85f4da7 100644
--- a/doc/manuals/chapters/remsim-server.adoc
+++ b/doc/manuals/chapters/remsim-server.adoc
@@ -13,11 +13,25 @@
 It is intended to make these settings (IP addresses, ports) configurable
 in future versions.
 
+==== SYNOPSIS
+
+*osmo-remsim-server* [-h] [-V] [-d LOGOPT]
+
+==== OPTIONS
+
+*-h, --help*::
+  Print a short help message about the supported options
+*-V, --version*::
+  Print the software version number
+*-d, --debug LOGOPT*::
+  Configure the logging verbosity, see <<remsim_logging>>.
+
 === Logging
 
-`osmo-remsim-server` currently logs to stdout only, and the logging
-verbosity is not yet configurable.  However, as the libosmocore logging
-framework is used, extending this is an easy modification.
+`osmo-remsim-server` currently logs to stderr only; the logging
+verbosity is configurable via command line argument only.  However, as
+the libosmocore logging framework is used, extending this is an easy
+modification.
 
 [[rsres]]
 === RESTful/JSON Web API
diff --git a/doc/manuals/osmo-remsim-usermanual.adoc b/doc/manuals/osmo-remsim-usermanual.adoc
index 1679db2..32f173b 100644
--- a/doc/manuals/osmo-remsim-usermanual.adoc
+++ b/doc/manuals/osmo-remsim-usermanual.adoc
@@ -16,6 +16,8 @@
 
 include::{srcdir}/chapters/remsim-bankd.adoc[]
 
+include::{srcdir}/chapters/logging.adoc[]
+
 include::{srcdir}/chapters/rspro.adoc[]
 
 //include::./common/chapters/vty.adoc[]

-- 
To view, visit https://gerrit.osmocom.org/c/osmo-remsim/+/26482
To unsubscribe, or for help writing mail filters, visit https://gerrit.osmocom.org/settings

Gerrit-Project: osmo-remsim
Gerrit-Branch: master
Gerrit-Change-Id: I66f5fe2e55c7e4cb6cc8ce09dcd8a636c717a5a0
Gerrit-Change-Number: 26482
Gerrit-PatchSet: 2
Gerrit-Owner: laforge <laforge at osmocom.org>
Gerrit-Reviewer: Jenkins Builder
Gerrit-Reviewer: fixeria <vyanitskiy at sysmocom.de>
Gerrit-Reviewer: laforge <laforge at osmocom.org>
Gerrit-MessageType: merged
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osmocom.org/pipermail/gerrit-log/attachments/20211209/c2df69b6/attachment.htm>

More information about the gerrit-log mailing list