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 @@ approach seems to make more sense. ==== 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 <>. *-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 @@ approach seems to make more sense. 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 @@ osmo-remsim-client-st2 currently has the following command-line options: *-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 <>. +*-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 @@ osmo-remsim-client-shell currently has the following command-line options: 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 <>. *-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 @@ bind to INADDR_ANY and offer the following TCP ports: 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 <>. + === 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-client.adoc[] include::{srcdir}/chapters/remsim-bankd.adoc[] +include::{srcdir}/chapters/logging.adoc[] + include::{srcdir}/chapters/rspro.adoc[] //include::./common/chapters/vty.adoc[]