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/.
Max gerrit-no-reply at lists.osmocom.orgReview at https://gerrit.osmocom.org/4154 logging: restructure sections The basic logging concepts like filters and levels which are target-independent. It's counter-intuitive that they are described inside vty target section. * fix that by putting them in separate sections which are referenced from target sections as necessary * move all targets into subsections under "Log targets" section Change-Id: I5acde815c66eb3d57e06ecd8dc65fe338216fe63 Related: OS#1913 --- M common/chapters/logging.adoc 1 file changed, 50 insertions(+), 30 deletions(-) git pull ssh://gerrit.osmocom.org:29418/osmo-gsm-manuals refs/changes/54/4154/1 diff --git a/common/chapters/logging.adoc b/common/chapters/logging.adoc index 28b6d3e..94fa898 100644 --- a/common/chapters/logging.adoc +++ b/common/chapters/logging.adoc @@ -25,34 +25,20 @@ configured by means of VTY commands that can either be entered interactively, or read from a configuration file at process start time. -=== Logging to the VTY +[[log_categories]] +=== Log categories -Logging messages to the interactive command-line interface (VTY) is most -useful for occasional investigation by the system administrator. - -Logging to the VTY is disabled by default, and needs to be enabled -explicitly for each such session. This means that multiple concurrent -VTY sessions each have their own logging configuration. Once you close -a VTY session, the log target will be destroyed and your log settings be -lost. If you re-connect to the VTY, you have to again activate and -configure logging, if you wish. - -To create a logging target bound to a VTY, you have to use the following -command: `logging enable` This doesn't really activate the -generation of any output messages yet, it merely creates and attaches a -log target to the VTY session. The newly-created target still doesn't -have any filter installed, i.e. __all log messages will be suppressed -by default__ - -Next, you can configure the log levels for your VTY session. Each -sub-system of the program in question typically logs its messages as a +Each sub-system of the program in question typically logs its messages as a different category, allowing fine-grained control over which log messages you will or will not see. For example, in OsmoBSC, there are categories for the protocol layers `rsl`, `rr`, `mm`, `cc` and many others. To get a a list of categories interactively on the vty, type: `logging level ?` -For each of those categories, you can set an independent log level, +[[log_levels]] +=== Log levels + +For each of the log categories (see <<log_categories>>), you can set an independent log level, controlling the level of verbosity. Log levels include: fatal:: @@ -84,12 +70,10 @@ Management category to info, you can use the following command: `log level mm info`. -Equally, to set the log level of the Call Control category to debug, you -can use: - `log level cc debug` +[[log_filters]] +=== Log filters -Finally, after having configured the levels, you still need to set the -filter. The default behavior is to filter out everything, i.e. not to +The default behavior is to filter out everything, i.e. not to log anything. The reason is quite simple: On a busy production setup, logging all events for a given subsystem may very quickly be flooding your console before you have a chance to set a more restrictive filter. @@ -101,13 +85,49 @@ subscriber identified by his IMSI, you may use: `log filter imsi 262020123456789` +=== Log targets + +Each of the log targets represent certain destination for log messages. +It can be configured independently by selecting levels (see <<log_levels>>) for categories +(see <<log_categories>>) as well as filtering (see <<log_filters>>) and +other options like `logging timestamp` for example. + +==== Logging to the VTY + +Logging messages to the interactive command-line interface (VTY) is most +useful for occasional investigation by the system administrator. + +Logging to the VTY is disabled by default, and needs to be enabled +explicitly for each such session. This means that multiple concurrent +VTY sessions each have their own logging configuration. Once you close +a VTY session, the log target will be destroyed and your log settings be +lost. If you re-connect to the VTY, you have to again activate and +configure logging, if you wish. + +To create a logging target bound to a VTY, you have to use the following +command: `logging enable` This doesn't really activate the +generation of any output messages yet, it merely creates and attaches a +log target to the VTY session. The newly-created target still doesn't +have any filter installed, i.e. __all log messages will be suppressed +by default__ + +Next, you can configure the log levels for desired categories in your VTY session. +See <<log_categories>> for more details on categories and <<log_levels>> for the log level details. + +For example, to set the log level of the Call Control category to debug, you +can use: + `log level cc debug` + +Finally, after having configured the levels, you still need to set the +filter as it's described in <<log_filters>>. + TIP: If many messages are being logged to a VTY session, it may be hard to impossible to still use the same session for any commands. We therefore recommend to open a second VTY session in parallel, and use one only for logging, while the other is used for interacting with the -system. +system. Another option would be to use different log target. -=== Logging to a file +==== Logging to a file As opposed to Logging to the VTY, logging to files is persistent and stored in the configuration file. As such, it is configured in @@ -139,7 +159,7 @@ implemented. -=== Logging to syslog +==== Logging to syslog syslog is a standard for computer data logging maintained by the IETF. Unix-like operating systems like GNU/Linux provide several syslog @@ -168,7 +188,7 @@ by issuing the `logging timestamp 0` command. -=== Logging to stderr +==== Logging to stderr If you're not running the respective application as a daemon in the background, you can also use the stderr log target in order to log to -- To view, visit https://gerrit.osmocom.org/4154 To unsubscribe, visit https://gerrit.osmocom.org/settings Gerrit-MessageType: newchange Gerrit-Change-Id: I5acde815c66eb3d57e06ecd8dc65fe338216fe63 Gerrit-PatchSet: 1 Gerrit-Project: osmo-gsm-manuals Gerrit-Branch: master Gerrit-Owner: Max <msuraev at sysmocom.de>