WebSphere brand IBM WebSphere Sensor Events, Version 6.2

Enabling logging and tracing for your Equinox or Eclipse launch configuration

This topic describes how to enable logging and tracing within Data Capture and Delivery.

How a log message flows through the system

Logging can be controlled in a number of places, each place influencing what is logged and where it is logged. In order to understand how to control the logging, it is important to understand how the messages flow through the system.

  1. When an agent tries to log a message, it first checks its own log.level property. If the log message is equal to or more severe than the value of the log.level property, then it sends the log message to the central logging system.
  2. The central logging system in the Alert agent checks its log level, which is the value of the org.eclipse.soda.sat.core.util.logLevel property. If the message is equal to or more severe than the system log level, then it is accepted by the logging system.
  3. Log messages are consumed by logging agents or other log consumers. Each one is dedicated to sending the log message to a different destination, such as the server, the console, a file, or so on.

    A logging agent compares the log event to the value of its log threshold property. If the log message is equal to or more severe than its threshold, then it forwards the log message as appropriate.

    • For the Alert agent, the log threshold value is set in the threshold property, and these messages are sent to the server.
    • For the Log File agent, the log threshold value is set in the log.threshold property, and these messages are written to a rotating set of files.
    • For the Console Log agent, the log threshold value is set in the log.threshold property, and these messages are sent to the WebSphere® Sensor Events Administrative Console, if the agent has been loaded.

    The debug export utility bundles do not have a threshold. They show all messages in the central logging system buffer. So, in effect, this is determined by the system log level, org.eclipse.soda.sat.core.util.logLevel.

In summary, the log level can be set at the controller level, the agent level, and the log consumer agent level. Log messages propagate only if they pass the agent's log level, the system log level, and the log consumer agent level.

Tracing

Tracing is a more detailed set of log messages than debug. You can set system-level tracing on the Alert agent using the org.eclipse.soda.sat.core.util.trace property. Use the tracing property on each agent to set agent-level tracing.

Setting the logging and tracing levels

To simplify the setting of these values across all controllers and agents, there are macros that have been defined in the WebSphere Sensor Events server and set as the default as indicated below:

System Log Level
Stored in %SYSTEM_LOG_LEVEL%. This is the default for the system log level, the org.eclipse.soda.sat.core.util.logLevel property value, for all controllers.
Agent Log Level
Stored in %AGENT_LOG_LEVEL%. This is the default log.level property value for all agents. By default, it is set to "", which means that it uses the system log level.
System Tracing
Stored in %SYSTEM_TRACE%. This is the default for the system trace level, the org.eclipse.soda.sat.core.util.trace property value, for all controllers.
Agent Tracing
Stored in %AGENT_TRACE%. This is the default tracing property value for all agents.

You can also change the value of a property for a specific controller or agent.

In addition, the following Console Log agent properties can be used to configure the level of messages displayed to the OSGi console without modifying the system log level:

Table 1. Console log agent properties and descriptions
Property Description
errorLogThreshold Minimum level of messages that are written to stderr. Valid values are none, error, warning, info, or debug.
logThreshold Minimum level of messages that are written to stdout. Valid values are none, error, warning, info, or debug. If the value is empty then the system log level is used.

Examples

If you want to log INFO level messages, and more severe ones, to a file, but you only want to send WARNING level messages to the server, do the following in the WebSphere Sensor Events Administrative Console:

  1. For the controller, set the System Log Level to INFO and set the Agent Log Level to "", meaning it should use the system log level.
  2. For the Alert agent, set the threshold property to WARNING.
  3. For the Log File agent, set the log.threshold to %SYSTEM_LOG_LEVEL%, or you can explicitly set it to INFO.

If you want to log DEBUG messages for one agent, but only INFO messages for other agents, and send all of those to a file, but you only want to send WARNING level messages to the server, do the following in the WebSphere Sensor Events Administrative Console:

  1. For the controller, set the System Log Level to DEBUG and set the Agent Log Level to INFO, so that it will be used by most agents.
  2. For the Alert agent, set the threshold property to WARNING.
  3. For the Log File agent, set the log.threshold to %SYSTEM_LOG_LEVEL%, or you can explicitly set it to DEBUG.
  4. For the agent that you want to deliver DEBUG messages, set the log.level to DEBUG, so that this one agent delivers more detailed messages.

If you want to log only WARNING messages, and more severe ones, but you only want to send INFO level messages to the server, this scenario is not possible. If only WARNING messages are sent to the logging system, then the INFO messages are dropped.

In most cases, the Log File agent's log.threshold property should be set to %SYSTEM_LOG_LEVEL%. This setting ensures that all detail logged to the system is captured, whether it is DEBUG or INFO, and it means that you do not need to change the property value when the system log level is changed.

Viewing messages and collecting logs

Install the com.ibm.rfid.console.log bundle into your runtime environment and start it to enable log messages from the agents to be seen on the OSGi console. When collecting a log to send with a problem report, be sure to retrieve the system properties by issuing the setprop command at the OSGI prompt. Also retrieve the list of installed bundles by issuing the ss command at the OSGI prompt.


Library | Support | Terms of use

(c) Copyright IBM Corporation 2004, 2009. All rights reserved.
U.S. Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.