Chapter 13
Logging
13.1 Introduction
REDHAWK provides a logging capability for use by all resources (Components, Devices, and Services). By default, the REDHAWK Framework and its support libraries have been developed to take advantage of the underlying language’s implementation: log4cxx, log4j, and log4py for C++, Java, and Python, respectively. All three libraries follow the basic premise of the log4j capabilities. A root logger definition is the parent of all loggers and configuration of the loggers is controlled through a JAVA style properties file. Each REDHAWK resource creates a named logger as a child of the root logger. (The name is based on the underlying resource’s name.) This chapter explains how to configure and use the logging capability. For a detailed description of log4j and its capabilities, refer to the log4j website. (http://logging.apache.org/log4j/1.2/)
All REDHAWK-generated code for resources provides an instantiation of a logging object for use by the resource. For Java and Python implementations, the underlying logging implementation of the language is used. For C++, there is a set of macro definitions that enable a resource to use the underlying logging implementation associated with the REDHAWK Core Framework library.
13.2 Configuring Logging Capabilities
A resource has the ability to provide a severity level (logging level) with each logging message. The following severity levels are listed in order of increasing verbosity. FATAL messages describe events that are unrecoverable to the resource, whereas DEBUG messages enable developers to understand the processing behavior.
- FATAL
- ERROR
- WARN
- INFO
- DEBUG
- TRACE
Each different logging implementation library uses a log4j configuration file format to define the configuration context for that library. This file defines how and where the logging messages are recorded. For example, if the configuration logging level is set to INFO, then messages published at the INFO, WARN, ERROR, and FATAL severity levels are displayed in the log. All other message levels are suppressed. The following two log-level configuration options are also available.
- OFF: Suppress all logging messages from the log
- ALL: Allow all logging messages
The following code displays the default log4j configuration settings used by all REDHAWK resources.
This configuration suppresses logging levels above INFO and writes those messages to the standard out console.
13.2.1 Configuration Context Tokens
For REDHAWK release 1.10 and above, the log4j configuration file can contain special tokens that expand to provide the runtime execution context of the resource. These tokens can be located anywhere in the configuration file and are resolved during resource startup. The following table, Table 13.1, describes the tokens.
|
Table 13.2 lists the availablity of token definitions for each REDHAWK resource type.
|
13.2.2 LOGGING_CONFIG_URI Resolution
For all REDHAWK resources, the command line argument LOGGING_CONFIG_URI provides the location of the logging configuration file to load for that resource. This section details how each resource type receives this parameter.
- Domain Manager: The Domain Manager is started via nodeBooter with the -D option.
The additional nodeBooter command line argument -logcfgfile is passed to the
Domain Manager as LOGGING_CONFIG_URI. The following lines describe acceptable
parameter values and their resolution:
- sca://path/to/config/file: $SDRROOT/dom/path/to/config/file
- file:///absolute/path/to/config/file: /absolute/path/to/config/file
- Device Manager: The Device Manager is started via nodeBooter with the -d option. The
additional nodeBooter command line argument -logcfgfile is passed to the Device
Manager as LOGGING_CONFIG_URI. The following lines describe acceptable parameter values
and their resolution:
- sca://path/to/config/file: $SDRROOT/dev/path/to/config/file
- file:///absolute/path/to/config/file: /absolute/path/to/config/file
- Device: A Device is started by the Device Manager. If the Device has a LOGGING_CONFIG_URI property with Pass on command line enabled, you can set the value via the Node’s dcd.xml file. This value is passed to the Device at startup; otherwise, the Device receives the value from the Device Manager’s LOGGING_CONFIG_URI command line argument.
- Service: A Service is started by the Device Manager. If the Service has a LOGGING_CONFIG_URI property with Pass on command line enabled, you can set the value via the Node’s dcd.xml file. This value is passed to the Service at startup; otherwise, the Service receives the value from the Device Manager’s LOGGING_CONFIG_URI command line argument.
- Component: A Component is started by a Device via the Domain Manager. If the Component has a LOGGING_CONFIG_URI property with Pass on command line enabled, you can set the value via the Waveform’s sad.xml file. This value is passed to the Component at startup; otherwise, the Component receives the value from the Domain Manager’s LOGGING_CONFIG_URI command line argument.
13.2.3 Log Configuration Example - Simple Appender with a Named Logger
In the following example, the root most logger passes logging messages with a severity level INFO or less. Those messages are sent to the appenders called: CONSOLE and FILE. The CONSOLE appender messages are displayed in the console of the running application. The FILE appender writes log messages to a file called allmsgs.out.
If the resource uses a named logger, EDET_cpp_impl1_i, then log messages with a severity of DEBUG or less are diverted to a file called edet_log.out.
13.2.4 Log Configuration Example - Configuring a Component with Token Macros
The logging configuration information for Component MEGA_WORKER is configured from $SDRROOT/dom/logcfg/component.log4j.cfg. Prior to configuring the underlying logging library, the configuration information is processed for the context macros (in this example, @@@WAVEFORM.NAME@@@, @@@COMPONENT.NAME@@@ and @@@COMPONENT.PID@@@). The root most logger passes logging messages with a severity level INFO or less, to the appenders called: CONSOLE and FILE. The CONSOLE appender messages are displayed in the console of the running application. For the FILE appender, the destination file is: /data/logdir/MY_EXAMPLE_1/MEGA_WORKER_1.212.log.
When the Waveform MY_EXAMPLE is deployed on the Domain, the Component is launched with the following logging configuration:MEGA_WORKER "....." LOGGING_CONFIG_URI sca://logcfg/component.log4j.cfg?fs=
IOR:010…
13.2.5 Logging with Event Channels for Components, Devices and Services
For REDHAWK resources, the underlying logging functionality has been extended to include support for publishing log messages to a specified Event Channel. To include this capability, add the the org.ossie.logging.RH_LogEventAppender in your log4j configuration file. This appender responds to the following configuration options (all options are string values unless otherwise noted):
|
The NAME_CONTEXT option, is required for C++ resources to maintain backwards compatablity. For REDHAWK 2.0 and greater resources developed in Python or JAVA, the EVENT_CHANNEL is acquired using the EventChannelManager interface that is available to resources with domain awareness and ignores the NAME_CONTEXT option.
Eventable logging is currently not supported for the Domain Manager and Device Manager. The following messages may occur during start up of these Services with configurations that use eventable logging.
In the following example, a Component configured with this log4j properties file publishes log messages with a severity of ERROR or less to the Event Channel ERROR_LOG_CHANNEL in the Domain, REDHAWK_DEV. The threshold level for the appender supersedes the rootLogger’s logging level.
13.3 Logging Within A Resource
Resource code generated using the REDHAWK code generators provides all the necessary prerequisites for establishing and configuring the logging capability.
13.3.1 C++
For C++ implementations, the generated REDHAWK code contains macro definitions that define a logger object with the class name for your resource. For example, for Component SigGen, the logger is SigGen_i.
13.3.1.1 Setup
The following example describes how to define and declare the SigGen_i logger.
13.3.1.2 Use
To add logging messages within your resource’s code, the following macros are available. These macros use the predefined class logger as the input parameter.
- LOG_FATAL(<component_class_name>, message text )
- LOG_ERROR(<component_class_name>, message text )
- LOG_WARN(<component_class_name>, message text )
- LOG_INFO(<component_class_name>, message text )
- LOG_DEBUG(<component_class_name>, message text )
- LOG_TRACE(<component_class_name>, message text )
The following example adds DEBUG-level logging messages to the predefined logger SigGen_i.
In addition to the resource’s predefined logger, you can request a new logger object using the rh_logger interface and named logger macros.
- RH_FATAL(logger_object, message text)
- RH_ERROR(logger_object, message text)
- RH_WARN(logger_object, message text)
- RH_INFO(logger_object, message text)
- RH_DEBUG(logger_object, message text)
- RH_TRACE(logger_object, message text)
The following example creates a new logger object (myLogger) and adds DEBUG-level logging messages to myLogger using the rh_logger interface.
13.3.2 Java
For Java implementations, the log4j logger module must be imported for use before the logging capability can be established and configured.
13.3.2.1 Setup
The following example describes how to import the log4j logger module.
13.3.2.2 Use
The following example describes how to enable the logger with DEBUG-level logging messages.
Log4j supports the following severity levels for logging and enables you to programmatically change the severity level of the logger object.
13.3.3 Python
13.3.3.1 Setup
All REDHAWK resources inherit from the Resource class, which defines the _log data member.
13.3.3.2 Use
An example logging method call for Python is:
REDHAWK has extended the Python logging support to include the trace method functionality. As with the other logging capabilities, you can programatically change the logging level.
13.4 Adjusting Logging at Runtime
The logging level for the root logger of a Component/Device can be adjusted at runtime in the IDE. The following procedure explains how to adjust the logging level.
- Right-click the running Component or Device and select Logging > Log Level.
The Set Debug Level dialog displays the current logging level.
- Select the new logging level you want to use and click OK.
The new log level is used.
After a Component or Device has been launched, its logging configuration can also be dynamically modified.
- Right-click the running Component or Device and select Logging > Edit Log Config. If this is the first time you have used the editor, a warning is displayed.
- If a warning is displayed, click Yes. The Edit Log Config editor is displayed.
The editor shows the resource’s logging configuration. Saving changes to the editor performs a live update of the resource’s logging configuration.
Changing the logging configuration for a running Application instance can affect the DomainManager process. When changing the logging configuration for an Application, restrict the configuration to an Application’s logging instance, Application_impl; as in the following example.
13.5 Viewing Logging Events
A live view of events logged by Components or Devices can be displayed in the IDE. The Component or Device provides logging events to an event channel, and the IDE displays them as it receives them. To view the log:
- Right-click the running Component or Device and select Logging > Tail Log. The
Specify logging details dialog is displayed.
- Select the logging level.
- If desired, specify the logger to which the IDE should attach. Leave the field blank to attach to the root logger.
- Click OK.
A new Console view displays logging events as they are received.
- To no longer view events, click the Stop icon on the Console toolbar.

REDHAWK Documentation is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.