Server Manager Logging - Part 3

Managed Home Agent Logging

OK, now on to the good stuff. The managed home agent, herein referred to as simply the agent, is responsible for a majority work performed by Server Manager (SM). This includes:

• registering/installing E1 managed instances
• registering and managing IBM WebSphere and Oracle Application Server
• managing the configuration file(s) for E1 managed instances
• starting/stopping E1 servers and the J2EE servers
• performing tools release upgrades/downgrades for E1 servers
• discovering and sending log files to the management console for viewing

You get the idea. The agent does most of the work. If anything goes wrong during one of these items, or your just an inquisitive person, the place you'll want to look to see what's going on are the agent's log files.

Logging Overview

Before we dig too far into the log files themselves let's get an understanding of the logging system used. Server Manager makes use of the standard java logging framework. This framework is different than the logging engine used by most other E1 software components which are based on the jdelog.properties configuration file.

The java logging framework exposes, and we make use of, seven levels of logging as outlined below in descending order

Level	Description
SEVERE	A critical error has occurred from the perspective of the agent. Critical errors are non-recoverable errors and require immediate attention. An example would be a critical problem when initializing the agent that would prevent it from starting or functioning properly.
WARNING	Denotes an abnormal or unexpected result occurred that is recoverable, from the perspective of the agent. An example would include a failure while changing the tools release of an E1 server. It is a significant problem, however, the agent will recover so is considered a warning.
INFO	Denotes informative messages providing contextual information as to what the agent is doing. An E1 server that is started using SM would have a log message indicating so at the INFO level.
CONFIG	Not commonly used in SM, a message at the configuration level is simply a means for logging information particular to that installation, such as the platform of the server.
FINE	A lower level message still intended as human readable that provides insight into what the agent is doing. This can be thought of as a standard "debug" message.
FINER	An even lower level trace of debug message. Messages are classified at this level rather than FINE if they are very frequently occurring and either less likely to be of interest.
FINEST	The lowest level of logging. These messages may be very frequent, verbose, or cryptic and may only be meaningful to Oracle development.

The division between SEVERE and WARNING is a little muddy. You may see messages that appear as SEVERE that really should be qualified as WARNING based on the above descriptions, and less frequently there may be a WARNING message that should have been classified as SEVERE.

The default logging level for the agent is FINE, which should be fine for nearly all troubleshooting needs. The agent is much less verbose than some of the other E1 products. Keeping the logging level at FINE, FINER, or even FINEST will have negligible impact on performance. There just aren't that many messages emitted to cause a problem.

Agent Log Location

The agent log files are located in the directory <agent_install>logs, where <agent_install> refers to the install location supplied during the managed home installer. The log files are named e1agent_#.log. The logging mechanism will automatically split log files into approximately 10 MB chunks, and up ten log files will be retained. That means the most amount of disk space needed for the agent logs is 100 MB. The '#' in the log name is the index of the log file with zero being the most recent and nine being the oldest. When the current log file, e1agent_0.log, reaches approximately 10 MB the last chunk (e1agent_9.log) will be deleted and all the log files will be renamed with the index incremented. The e1agent_0.log is now e1agent_1.log and a new e1agent_0.log file will be created. Another file, 'e1agent_0.log.lck' may also be present. This file is created by Java as a lock file and may be ignored.

The log files for the agent may be viewed directly through the management console directly. From the management dashboard (start page) select the managed home of interest.

At the bottom of the page for the selected managed home is a log files section.

Selecting a log file will transfer the log from the remote machine to the management console so it may be viewed using the integrated log viewer, as shown below.

Each log message consists of two or more lines. The first line contains the timestamp, originating java class, and the name of the current method from which the message was written. The second line (or multiple lines) contains the actual log message.

Changing Logging Levels

The default level for agent logging is FINE, which is appropriate for most occasions. It may be desirable to change the level to FINER or FINEST to troubleshoot an issue, or move it to a higher level, such as INFO, for some reason. If the agent is running and connected to a management console you may change the level directly from the console. Located on the left hand side of the page for the management agent is a section entitled 'Managed Home Details'. In there is a dropdown for 'Agent Log Level'. The current value will be shown.

To change the level simply select the desired log level from the drop down list. The change will immediately take effect. Changing the log level through this dropdown is not permanent; when the agent is restarted it will resume logging at the FINE level.

If you wish to permanently change the logging level, or you will to set the level to something other than FINER during agent startup, you may add the following line to the <agent_install>/config/agent.properties file.

log.level=FINER

You may use any of the log levels mentioned in the table above, or OFF to prevent all logging.

I do not recommend permanently keeping the log level at OFF, SEVERE, WARNING, CONFIG, or INFO. You never know when you may need the additional information provided by the FINE level. The agent will automatically remove old log files so there should be no concern of log files filling a disk.

Embedded Agent Logging

The E1 enterprise server and E1 HTML server all contain variants of the management agent. In the embedded form the logging messages generated by the management agent are not typically logged. It may be desired to enable the same logging for the embedded management agents. To do so simply add the following line to the <agent_install>/config/agent.properties file.

log.embedded.instances=true

After adding this line and restarting the E1 managed instance series of log files will appear in the <agent_install>/logs directory. The filename of the log files will be the instance name of the E1 server.

It is very rare to need to enable this logging; that said it may be useful to troubleshoot why the embedded agents may not be communicating with the management console.

This form of logging is not available to an E1 web server if it is deployed to a federated (e.g. network deployment) node in IBM WebSphere.

Final Thoughts

Stack Traces: some log messages may contain stack traces. This information is useful for identifying the source of the message. A stack trace is not always indicative of a problem. The level of the message is much more indicative. Stack traces for INFO, FINE, FINER, or FINEST messages are included to provide more information and is not an error.