View on GitHub

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.

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.

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.




Token

Definition



@@@HOST.NAME@@@

Host name returned from gethostname call (multi-homed systems may have issues).



@@@HOST.IP@@@

Dot notation IP Address of the machine on which the processing is running.



@@@NAME@@@

Name of the resource given on the command line.



@@@INSTANCE@@@

Instance name given to the resource on the command line.



@@@PID@@@

PID of the running resource.



@@@DOMAIN.NAME@@@

Name of the Domain under which your resource is running.



@@@DOMAIN.PATH@@@

The contents of the DOM_PATH parameter on the command line.



@@@DEVICE_MANAGER.NAME@@@

Name of the Device Manager that started the Device or Service.



@@@DEVICE_MANAGER.INSTANCE@@@

Instance name of the Device Manager from the command line.



@@@SERVICE.NAME@@@

Name of the Service as specified on the command line.



@@@SERVICE.INSTANCE@@@

Instance name of the Service as specified on the command line.



@@@SERVICE.PID@@@

PID of the running Service.



@@@DEVICE.NAME@@@

Name of the Device as specified on the command line.



@@@DEVICE.INSTANCE@@@

Instance name of the Device as specified on the command line.



@@@DEVICE.PID@@@

PID of the Device.



@@@WAVEFORM.NAME@@@

Name of the Waveform from the DOM_PATH command line variable.



@@@WAVEFORM.INSTANCE@@@

Instance name of the Waveform from the DOM_PATH command line variable.



@@@COMPONENT.NAME@@@

Name of the Component binding parameter as specified on the command line.



@@@COMPONENT.INSTANCE@@@

Instance name of the Component identifier parameter as specified on the command line.



@@@COMPONENT.PID@@@

PID of the Component.


Table 13.1: log4j Configuration File Special Tokens

Table 13.2 lists the availablity of token definitions for each REDHAWK resource type.








Token

Domain
Manager

Device
Manager

Device

Service

Component







@@@HOST.IP@@@

Y

Y

Y

Y

Y







@@@HOST.
NAME@@@

Y

Y

Y

Y

Y







@@@NAME@@@

Domain
Manager

Y

Y

Y

Y







@@@INSTANCE@@@

DOMAIN_
MANAGER_1

Y

Y

Y

Y







@@@PID@@@

Y

Y

Y

Y

Y







@@@DOMAIN.
NAME@@@

Y

Y

Y

Y

Y







@@@DOMAIN.
PATH@@@

Y

Y

Y

Y

Y







@@@DEVICE_MANAGER.
NAME@@@

N

DEVICE_
MANAGER

Y

Y

N







@@@DEVICE_MANAGER.
INSTANCE@@@

N

Y

Y

Y

N







@@@SERVICE.
NAME@@@

N

Y

N

Y

N







@@@SERVICE.
INSTANCE@@@

N

Y

N

Y

N







@@@SERVICE.PID@@@

N

Y

N

Y

N







@@@DEVICE.
NAME@@@

N

Y

Y

N

N







@@@DEVICE.
INSTANCE@@@

N

Y

Y

N

N







@@@DEVICE.
PID@@@

N

Y

Y

N

N







@@@WAVEFORM.
NAME@@@

N

N

N

N

Y







@@@WAVEFORM.
INSTANCE@@@

N

N

N

N

Y







@@@COMPONENT.
NAME@@@

N

N

N

N

Y







@@@COMPONENT.
INSTANCE@@@

N

N

N

N

Y







@@@COMPONENT.
PID@@@

N

N

N

N

Y


Table 13.2: Availability of Tokens

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.

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):




Appender Option

Description



EVENT_CHANNEL

Event Channel name where logging messages are published.



NAME_CONTEXT

Directory in omniNames to lookup Event Channel (Domain name - REDHAWK_DEV).



PRODUCER_ID

Identifier of the resource producing the log message (resource name).



PRODUCER_NAME

Name of the resource producing the log message.



PRODUCER_FQN

Fully qualified name of the resource (Domain-name/Waveform-name/resource-name).



RETRIES

Number of times to retry connecting to the Event Channel. (Integer)



THRESHOLD

log4cxx log level; FATAL, WARN, ERROR, INFO, DEBUG, TRACE.


Table 13.3: RH_LogEventAppender Configuration Options

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.

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.

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.

  1. Right-click the running Component or Device and select Logging > Log Level.

    The Set Debug Level dialog displays the current logging level.


    PIC
    Figure 13.1: Set Debug Level


  2. 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.

  1. 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.
  2. If a warning is displayed, click Yes. The Edit Log Config editor is displayed.
    PIC
    Figure 13.2: Edit Log Config Editor


    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:

  1. Right-click the running Component or Device and select Logging > Tail Log. The Specify logging details dialog is displayed.


    PIC
    Figure 13.3: Edit Log Config Editor


  2. Select the logging level.
  3. If desired, specify the logger to which the IDE should attach. Leave the field blank to attach to the root logger.
  4. Click OK.

    A new Console view displays logging events as they are received.

  5. To no longer view events, click the Stop icon on the Console toolbar.


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