RI PC Platform Logging

Introduction

Platform Logging

In an effort to provide a flexible logging solution, we are incorporating the log4c library into the RI Platform repository. This solution should be flexible enough to accomodate the multiprocess/network debugging requirement that the architecture exposes.
log4c is part of a larger family of log4x logging utilities that originated after the Apache's log4j Java library. It supports categories, allowing one to enable/disable modular logging as well as up to seven logging levels (see Platform Logging level descriptions, below for an update to this), each providing different verbosity and semantics. It also comes with a powerful library of appenders, which allows for customizing the logging output to use different output facilities such as terminals, files or network protocols.

log4c is available under the LGPL 2.1 license. More information about the library can be found at this location. A nice developer's guide may be downloaded from http://www.slideshare.net/gzm55/log4-c-developers-guide-presentation.

Stack Logging

At the OCAP stack level, log4j is employed for logging. Messages generated by log4j are funneled through the above-mentioned log4c system so that stack log messages are merged into the stream of platform log messages.

Pipeline Logging

GStreamer libraries make use of a logging system that has been defined by the GStreamer development team. As is done for Stack logging, log messages generated by the GStreamer libraries are merged into the overall stream of platform log messages.
This page is not intended to fully document Log4c, Log4j, or the GStreamer logging systems themselves, but to describe how to configure and use the logging systems in the RI projec to produce useful logging output.

Logging System Design Description

For a more complete description of the design of the logging system please see this page.

Quick Start

The Platform configuration file log4crc is located in the $PLATFORMROOT directory is used to configure the Log4c logging system. As delivered, the Platform has all logging levels set so that FATAL and ERROR events are captured to the log. This results in a very terse log that only records events that indicating a significant impairment of the ability of the RI system to operate satisfactorily.
The Stack configuration file mpeenv.ini is located in the $OCAPROOT/bin/$OCAPTC/env directory and is used to configure log4j Stack logging system. By editing this file, one can set logging levels for specific categories in the stack in a manner similar to setting levels for the platform. Additional information on stack logging configuration may be found below.

GStreamer logging configuration is included in a section of the platform.cfg file located in the $PLATFORMROOT directory. Addional information on GStreamer logging may be found below as well.

To view more detailed information about specific categories, setting the logging level for a specific category to INFO in the configuration files should allow for observation of more detailed, domain-level, system behavior. For example: Successfully tuned to service ocap:0x2f79 Successfully opened file 'XXXXXXX' for reading etc.

See below for definitions of the various logging levels, categories, and how they can be configured.

Platform Logging level descriptions

Log4C defines 11 priority levels for logging that provide a very fine level of granularity for messages. With so many developers working on the project, there is much opportunity for inconsistencies regarding which priority levels are appropriate for the messages to be logged. Therefore, the RI project has limited the number of priorities to 6. Here we refer to a best practices document (http://www.ja-sig.org/wiki/display/UPC/LoggingBestPractices) for descriptions of the various logging levels:

• FATAL log messages are messages about failures so core to what your component does that it simply cannot continue, will not recover, and is throwing in the towel. Inability to connect to your must-have database is probably FATAL. Anything that keeps the Portal from starting at all is FATAL. FATAL is not for the minor inconveniences of life, though – if your Weather channel can't get an updated forcast on the first try but is designed to retry periodically and this is just the first try, that's just not FATAL. Maybe it's...

• ERROR should be reserved for genuine errors in your component – problems from elsewhere that you are reporting or coping with successfully are probably more WARNings than ERRORs. This way a deployer can set log level ERROR for your component and thereby filter out all the noise, obtaining just the ERRORs in your component itself.

• WARNings are likely problems that are recovered from, perhaps. Warning, I'm not behaving ideally here, but I nonetheless can have some fallback behavior that makes sense.

• INFOrmation should inform a deployer – not about problems (those are WARNings or ERRORs) – but informative nonetheless. INFOrmation is log messages a Portal administrator or deployer plausibly would welcome receiving. Of course, your sysadmin or deployer may turn off or on INFO level logging as she sees fit – I'm just saying that when she turns on INFO, it should be informative.

This level of information can be thought of as domain-level tracing.

• DEBUG is lower level information concerning program logic decisions, internal state, etc. Running a component with DEBUG logging should result in a log that narrates the choices and behaviors of the component.

• TRACE is the finest granularity logging level. Ideally, TRACE should result in logging of entrance and exit of every method of your class, logging the state of the class. Plausibly, only the component developer or the poor guy eight months later performing code maintenance will ever run your component with TRACE on. TRACE is in some sense an alternative to running an interactive debugger. Don't get me wrong - both approaches have their niche. But the result from exercising a component under TRACE is conceptually similar to the approach of stepping through it.

Platform Logging Categories

In the Log4C system each message to be logged is associated with a category. Categories are defined hierarchically in the source code (where '.'s are used to separate the hierarchical levels), and typically correspond to identifiable source code components. If a category appears in the log4crc configuration file, it is said to be 'configured', and the logging level for that category can be explicitly specified. Categories that do not appear in the log4crc configuration file are 'unconfigured' categories, and their logging levels will default to that specified for ancestral categories. Note that for the RI project, the root category is named 'RI', and is always configured.
Following is a list of the categories defined in the RI project:

RI
The top-level category declared in the log4crc file. Any categories that do not have levels associated with them will inherit the level associated with this category.

RI.GLib
Delivers output from the GLib (Gnome) libraries. For example GArrays, GLists, etc.

RI.GST_Utils
GStreamer utilities module. Note that this module is specific to the RI project, and not part of the GStreamer libraries themselves.

RI.Pipeline
Top-level pipeline category, associated with the pipeline.c module.

RI.Pipeline.IB
In-band section filtering portion of the 'live' pipeline, associated with the ib_section_filter.c module.

RI.Pipeline.OOB
Out-of-band section filter associated with the oob_pipeline.c module.

RI.Pipeline.TSB
Time shift buffer associated with the tsb.c module.

RI.DRI.TUNER
Digital Receiver Interface tuner category, associated with the dri_tuner.c module.

RI.DRI.FDC
Forward Data Channel category, associated with the dri_Fdc.c module.

RI.Platform
Main platform startup and initialization associated with the platform.c module.

RI.BackPanel
Represents the 'back panel' of an OCAP Host Device, associated with the backpanel.c module.

RI.SectionCache
Manages a cache of sections delivered by the GStreamer pipeline, associated with the section_cache.c module.

RI.SectionFilter
Section filter implementation, associated with the section_filter.c module.

RI.SectionFilter.OOB
Out-ob-band section filter implementation, associated with the oob_section_filter.c module.

RI.Stack
Handles debug messages from the stack layer, directly associated with the ui_manager.c module, indirectly associated with the general stack source. This is essentially a pass-through category for stack layer messages.

RI.UIManager
Although associated with the ui_manager.c module, it doesn't appear that any messages are actually logged using this category.

RI.IFS
Indexing file system implementation, associated with the IfsImpl.c module.

RI.IFS.Remap
Assumed to be associated with the PID remapping system, RemapImpl.c

RI.Tuner
Models the tuner of an OCAP Host Device, associated with the tuner.c module.

RI.HDHR.Tuner
Manages the HD Home Run ATSC tuner device, associated with the hdhr_Tuner.c module.

RI.VLC.Tuner
Manages the VLC software tuner, associated with the vlc_Tuner.c module.

RI.Display
Models the video display of an OCAP Host Device, associated with the display.c module

RI.UI
Manages the low-level on-screen window and key input handling, associated with the ui_window.cpp module.

RI.UI.TvScreen
Manages the on-screen tv screen GUI element, associated with RITvScreen.cpp module.

RI.UI.Console
Manages teh on-screen 'console' GUI element, associated with the RIConsole.cpp module.

RI.UI.Remote
Manages the on-screen remote control GUI element, associated with the RIRemote.cpp module.

RI.UI.FrontPanel
Manages the on-screen front panel GUI element, associated with the RIFrontPanel.cpp module.

RI.UI.OpenGL.common
Manages the common functionality related to composting of video and graphics on the display screen using OpenGL, associated with the ui_opengl_common.c module.

RI.UAL
Root UPnP Adaptation Layer (UAL) category, associated with the ual.c module.

RI.UAL.ual
General UAL functionality category, associated with the ual.c module.

RI.UAL.ssdp
Management of UPnP entities discovered using the UPnP discovery protocol SSDP, associated with the uPnP_ssdp.c module.

RI.UAL.ctrlpt
Implementation of UPnP Control Point, associated with the uPnP_ctrlpt.c, uPnP_testapp.c, and ual_examples.c modules.

RI.UAL.util
Some general utilities helpful for working with UPnP elements, associated with the uPnP_util.c module.

RI.UAL.test
Declared in the ual.c module, this category appears to be unused.

Platform Logging Configuration

Platform logging configuration resides in the $PLATFORMROOT/log4crc file. The best way to understand how to fully configure the logging system is to study the log4c documentation. However, this section includes some discussion regarding configuration of log4c as delivered with the RI.
Top-level category The top level is specified to be 'RI'. Unless specified otherwise, all sub-categories will inherit the priority associated with this category.

Top-level priority: When deployed, it is assumed that the operator will be primarily interested in fatal and significant events which may indicate an error condition. Therefore, the default top-level default priority is set to ERROR.

Appender: The RI project has defined an appender that appends logging information from each execution of the RI to a file called RILog.txt that is written to the $PLATFORMROOT directory.

To have the log file replaced each time the RI is executed, change the type attribute of this appender from stream_env_append_plus_stdout to stream_env_plus_stdout.

More compact logs can be created by not including date/time information for each log message. This can be accomplished by changing the layout attribute from dated to basic.

Note that the RI.Stack category has a default priority of trace. This configuration allows Stack-level messages to pass through the platform logging system.

Stack Logging

The stack has its own logging system with categories and levels that are configured in the $OCAPROOT/bin/$OCAPTC/env/mpeenv.ini file. Log messages originated by the stack are processed by the log4j logging utility and presented to the RI platform so that they are merged into the RI Platform's log output.
Stack log messages can be identified in the RILog.txt file by the prefix RI.Stack.

Stack Logging Categories

The following are categories that are defined for logging at the stack level. Categories marked with .ini are configured in the mpeenv.ini file. The remaining categories are declared in the source code, but are not configured in the mpeenv.ini file. For detailed information about the definition of these categories, see the header file $OCAPROOT/mpe/include/mpe_dbg.h.
LOG.MPE.TARGET .ini
The port-specific to the target device.

LOG.MPE.CC .ini
Closed captioning API logging.

LOG.MPE.CDL
Common Download logging.

LOG.MPE.COND .ini
Conditional logging.

LOG.MPE.DBG .ini
Debug API logging

LOG.MPE.DIRECTFB .ini
DirectFB logging.

LOG.MPE.DISP .ini
Display API logging.

LOG.MPE.DLL .ini
Dynamic Link Library (DLL) management API logging.

LOG.MPE.DVR .ini
Digital Video Recording (DVR) API logging.

LOG.MPE.EVENT .ini
Event API logging.

LOG.MPE.ED .ini
Event Dispatch API logging.

LOG.MPE.FILESYS .ini
File System API logging.

LOG.MPE.FILTER .ini
Filtering API logging.

LOG.MPE.HN
Home Networking API logging.

LOG.MPE.VBI
Vertical Blanking Interval (VBI) API logging.

LOG.MPE.FP .ini
Front Panel API logging.

LOG.MPE.GFX .ini
Graphics API logging.

LOG.MPE.JAVA .ini
Java code logging.

LOG.MPE.JNI .ini
Java Native Interface logging.

LOG.MPE.JNI:AWT
Java Abstract Windowing Toolkit API logging.

LOG.MPE.JVM .ini
Java Virtual Machine logging.

LOG.MPE.MEDIA .ini
Media API logging.

LOG.MPE.MEM .ini
Memory API logging.

LOG.MPE.MUTEX .ini
Thread synchronization API logging.

LOG.MPE.NET .ini
Network API logging.

LOG.MPE.OS .ini
Operating System API logging.

LOG.MPE.POD .ini
Point of Deployment (aka CableCARD) API logging.

LOG.MPE.SI .ini
Service Information API logging.

LOG.MPE.SOUND .ini
Sound playback logging.

LOG.MPE.SYS .ini
System Manager logging.

LOG.MPE.TEST .ini
MPE testing framework logging.

LOG.MPE.THREAD .ini
Thread API logging.

LOG.MPE.UTIL .ini
Utility API logging.

LOG.MPE.UI .ini
User interface logging.

LOG.MPE.MRDVR
Multi-room DVR logging.

LOG.MPE.SNMP
Simple Network Management Protocol (SNMP) logging.

LOG.MPE.STORAGE .ini
Storage logging.

LOG.MPE.PROD
Production logging module logging.

LOG.MPE.FDR
FDR logging (what is this?).

Configuring Stack Logging

The default or 'root' logging level is specified by the 'LOG.MPE.DEFAULT' entry in the $OCAPROOT/bin/$OCAPTC/env/mpeenv.ini file. This is the logging level that will be enforced for all categories in the absence of any other specified logging level.
To enable lower level logging for specific categories, specify the desired logging level for that category in the mpeenv.ini file. This is typically done by uncommenting (by removing the preceding '#' character from) the desired category in the file. Specifying 'ALL' enables the fatal, error, warn, and info logging levels.

Does the 'DEBUG' level have any meaning? I don't see where it is handled in the parseLogConfig() function What about 'EnableMPELog' in the mpeenv.ini file - it looks like it is referenced in mpeos_dbg.c, but I don't see where it is really used ?

GStreamer Pipeline Logging

Logging events related to the GStreamer implementation included in the RI can be configured by editing the RI.Platform.gstargs.X entries in the $PLATFORMROOT/platform.cfg file. Note that the RI logging system essentially provides pass-through configuration the GStreamer libraries using standard GStreamer logging configurations. Readers who are interested in configuring GStreamer pipeline logging should refer to the GStreamer documentation for details. The notes in the platform.cfg file should then be sufficient to allow one to sufficiently configure GStreamer pipeline logging.
Developers should note that GStreamer defines 5 logging levels, the names of which do not exactly match those defined by Log4C. Here are the GStreamer levels and the Log4C levels they map to:

Viewing Log files

The log files can be viewed using the conventional means of opening the file in an editor, or by 'tailing' it. Another nifty tool to use is Chainsaw, which can be configured so that the log messages are highlighted using different colors based on the message's log level. Scott D.- what would you like to contribute here?