<p>laforge <strong>submitted</strong> this change.</p><p><a href="https://gerrit.osmocom.org/c/osmo-remsim/+/26482">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Jenkins Builder: Verified
fixeria: Looks good to me, but someone else must approve
laforge: Looks good to me, approved
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">manual: Document the logging configuration<br><br>Change-Id: I66f5fe2e55c7e4cb6cc8ce09dcd8a636c717a5a0<br>---<br>A doc/manuals/chapters/logging.adoc<br>M doc/manuals/chapters/remsim-bankd.adoc<br>M doc/manuals/chapters/remsim-client.adoc<br>M doc/manuals/chapters/remsim-server.adoc<br>M doc/manuals/osmo-remsim-usermanual.adoc<br>5 files changed, 90 insertions(+), 6 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/manuals/chapters/logging.adoc b/doc/manuals/chapters/logging.adoc</span><br><span>new file mode 100644</span><br><span>index 0000000..bf4ebe5</span><br><span>--- /dev/null</span><br><span>+++ b/doc/manuals/chapters/logging.adoc</span><br><span>@@ -0,0 +1,58 @@</span><br><span style="color: hsl(120, 100%, 40%);">+[[remsim_logging]]</span><br><span style="color: hsl(120, 100%, 40%);">+== osmo-remsim logging</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+All programs within the osmo-remsim project use the logging sub-system of `libosmocore`.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Contrary to the larger Osmocom projects with their own VTY + configuration file, the</span><br><span style="color: hsl(120, 100%, 40%);">+logging configuration for osmo-remsim programs must happen via command line arguments.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Also, contrary to the larger Osmocom projects, only logging to `stderr` is supported;</span><br><span style="color: hsl(120, 100%, 40%);">+no direct logging to log files, syslog, systemd, etc. is supported at this point.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== `-d` command line argument</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Every osmo-remsim program like `osmo-remsim-bankd`, `osmo-remsim-server` or</span><br><span style="color: hsl(120, 100%, 40%);">+`osmo-remsim-client-st2` supports a `-d` command line argument. This argument</span><br><span style="color: hsl(120, 100%, 40%);">+takes one mandatory parameter configuring the log level for each log sub-system</span><br><span style="color: hsl(120, 100%, 40%);">+as follows:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`-d SUBSYS,num_lvl[:SUBSYS,num_lvl[:...]]`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+So basically, a colon-separated list of tuples, where each tuple contains the</span><br><span style="color: hsl(120, 100%, 40%);">+sub-system name and the _numeric_ log level.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Below is the list of sub-systems and a table of numerical levels:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.libosmocore log levels and their numeric values</span><br><span style="color: hsl(120, 100%, 40%);">+[options="header",width="30%",cols="1,1"]</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+|Level name|Numeric value</span><br><span style="color: hsl(120, 100%, 40%);">+|DEBUG|1</span><br><span style="color: hsl(120, 100%, 40%);">+|INFO|3</span><br><span style="color: hsl(120, 100%, 40%);">+|NOTICE|5</span><br><span style="color: hsl(120, 100%, 40%);">+|ERROR|7</span><br><span style="color: hsl(120, 100%, 40%);">+|FATAL|8</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+.osmo-remsim log sub-system names and their description</span><br><span style="color: hsl(120, 100%, 40%);">+[options="header",width="50%",cols="1,2"]</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+|Sub-System Name|Description</span><br><span style="color: hsl(120, 100%, 40%);">+|DMAIN|respective main program code</span><br><span style="color: hsl(120, 100%, 40%);">+|DST2|SIMtrace2 `cardem` firmware interaction via USB</span><br><span style="color: hsl(120, 100%, 40%);">+|DRSPRO|RSPRO protocol between bankd, server and client</span><br><span style="color: hsl(120, 100%, 40%);">+|DREST|REST interface of `osmo-remsim-server`</span><br><span style="color: hsl(120, 100%, 40%);">+|DSLOTMAP|slotmap code shared by `osmo-remsim-server` and `osmo-remsim-bankd`</span><br><span style="color: hsl(120, 100%, 40%);">+|DBANKDW|worker threads of `osmo-remsim-bankd`</span><br><span style="color: hsl(120, 100%, 40%);">+|===</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+=== Example</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+Putting the above in a concrete example:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+`-d DMAIN,5:DRSPRO,1`</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+would perform the following configuration:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+* log only NOTICE (or higher) messages in the DMAIN subsystem (low verbosity)</span><br><span style="color: hsl(120, 100%, 40%);">+* log DEBUG (or higher) messages in the DRSPRO subsystem (very high verbosity)</span><br><span>diff --git a/doc/manuals/chapters/remsim-bankd.adoc b/doc/manuals/chapters/remsim-bankd.adoc</span><br><span>index ab7a362..da529e2 100644</span><br><span>--- a/doc/manuals/chapters/remsim-bankd.adoc</span><br><span>+++ b/doc/manuals/chapters/remsim-bankd.adoc</span><br><span>@@ -61,12 +61,16 @@</span><br><span> </span><br><span> ==== SYNOPSIS</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-*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> ]</span><br><span style="color: hsl(120, 100%, 40%);">+*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> ]</span><br><span> </span><br><span> ==== OPTIONS</span><br><span> </span><br><span> *-h, --help*::</span><br><span> Print a short help message about the supported options</span><br><span style="color: hsl(120, 100%, 40%);">+*-V, --version*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Print the software version number</span><br><span style="color: hsl(120, 100%, 40%);">+*-d, --debug LOGOPT*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Configure the logging verbosity, see <<remsim_logging>>.</span><br><span> *-i, --server-host A.B.C.D*::</span><br><span> Specify the remote IP address/hostname of the `osmo-remsim-server` to</span><br><span> which this bankd shall establish its RSPRO control connection</span><br><span>@@ -83,7 +87,7 @@</span><br><span> Specify the local IP address to which the socket for incoming connections</span><br><span> from `osmo-remsim-clients` is bound to.</span><br><span> *-P, --bind-port <1-65535>*::</span><br><span style="color: hsl(0, 100%, 40%);">- Specify the local TCP port to whicc the socket for incoming connections</span><br><span style="color: hsl(120, 100%, 40%);">+ Specify the local TCP port to which the socket for incoming connections</span><br><span> from `osmo-remsim-client`s is bound to.</span><br><span> </span><br><span> ==== Examples</span><br><span>diff --git a/doc/manuals/chapters/remsim-client.adoc b/doc/manuals/chapters/remsim-client.adoc</span><br><span>index 5e17ec0..f2ee952 100644</span><br><span>--- a/doc/manuals/chapters/remsim-client.adoc</span><br><span>+++ b/doc/manuals/chapters/remsim-client.adoc</span><br><span>@@ -72,7 +72,11 @@</span><br><span> </span><br><span> *-h, --help*::</span><br><span> Print a short help message about the supported options</span><br><span style="color: hsl(0, 100%, 40%);">-*-s, --server-host A.B.C.D*::</span><br><span style="color: hsl(120, 100%, 40%);">+*-V, --version*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Print the software version number</span><br><span style="color: hsl(120, 100%, 40%);">+*-d, --debug LOGOPT*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Configure the logging verbosity, see <<remsim_logging>>.</span><br><span style="color: hsl(120, 100%, 40%);">+*-i, --server-ip A.B.C.D*::</span><br><span> Specify the remote IP address / hostname of the `osmo-remsim-server` to</span><br><span> which this client shall establish its RSPRO control connection</span><br><span> *-p, --server-port <1-65535>*::</span><br><span>@@ -220,6 +224,8 @@</span><br><span> Print a short help message about the supported options</span><br><span> *-v, --version*::</span><br><span> Print the compile-time version information</span><br><span style="color: hsl(120, 100%, 40%);">+*-d, --debug LOGOPT*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Configure the logging verbosity, see <<remsim_logging>>.</span><br><span> *-i, --server-ip A.B.C.D*::</span><br><span> Specify the remote IP address / hostname of the `osmo-remsim-server` to</span><br><span> which this client shall establish its RSPRO control connection</span><br><span>diff --git a/doc/manuals/chapters/remsim-server.adoc b/doc/manuals/chapters/remsim-server.adoc</span><br><span>index 304a7f3..85f4da7 100644</span><br><span>--- a/doc/manuals/chapters/remsim-server.adoc</span><br><span>+++ b/doc/manuals/chapters/remsim-server.adoc</span><br><span>@@ -13,11 +13,25 @@</span><br><span> It is intended to make these settings (IP addresses, ports) configurable</span><br><span> in future versions.</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+==== SYNOPSIS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*osmo-remsim-server* [-h] [-V] [-d LOGOPT]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+==== OPTIONS</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+*-h, --help*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Print a short help message about the supported options</span><br><span style="color: hsl(120, 100%, 40%);">+*-V, --version*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Print the software version number</span><br><span style="color: hsl(120, 100%, 40%);">+*-d, --debug LOGOPT*::</span><br><span style="color: hsl(120, 100%, 40%);">+ Configure the logging verbosity, see <<remsim_logging>>.</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> === Logging</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-`osmo-remsim-server` currently logs to stdout only, and the logging</span><br><span style="color: hsl(0, 100%, 40%);">-verbosity is not yet configurable. However, as the libosmocore logging</span><br><span style="color: hsl(0, 100%, 40%);">-framework is used, extending this is an easy modification.</span><br><span style="color: hsl(120, 100%, 40%);">+`osmo-remsim-server` currently logs to stderr only; the logging</span><br><span style="color: hsl(120, 100%, 40%);">+verbosity is configurable via command line argument only. However, as</span><br><span style="color: hsl(120, 100%, 40%);">+the libosmocore logging framework is used, extending this is an easy</span><br><span style="color: hsl(120, 100%, 40%);">+modification.</span><br><span> </span><br><span> [[rsres]]</span><br><span> === RESTful/JSON Web API</span><br><span>diff --git a/doc/manuals/osmo-remsim-usermanual.adoc b/doc/manuals/osmo-remsim-usermanual.adoc</span><br><span>index 1679db2..32f173b 100644</span><br><span>--- a/doc/manuals/osmo-remsim-usermanual.adoc</span><br><span>+++ b/doc/manuals/osmo-remsim-usermanual.adoc</span><br><span>@@ -16,6 +16,8 @@</span><br><span> </span><br><span> include::{srcdir}/chapters/remsim-bankd.adoc[]</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+include::{srcdir}/chapters/logging.adoc[]</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> include::{srcdir}/chapters/rspro.adoc[]</span><br><span> </span><br><span> //include::./common/chapters/vty.adoc[]</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.osmocom.org/c/osmo-remsim/+/26482">change 26482</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.osmocom.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.osmocom.org/c/osmo-remsim/+/26482"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: osmo-remsim </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I66f5fe2e55c7e4cb6cc8ce09dcd8a636c717a5a0 </div>
<div style="display:none"> Gerrit-Change-Number: 26482 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-Reviewer: Jenkins Builder </div>
<div style="display:none"> Gerrit-Reviewer: fixeria <vyanitskiy@sysmocom.de> </div>
<div style="display:none"> Gerrit-Reviewer: laforge <laforge@osmocom.org> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>