* Title: What is Dynamic DEBUG_OUTFILE in Domino 6?
* Product Area: Domino Server
* Product Release: Domino Server 6.0
* Topic: Server \\ Administration \\ Server Console
Document #: 194060
Last Update: 09/30/2002
(?) Circulation: Published - This document is technically verified and technically edited.
Problem:
What is the dynamic DEBUG_OUTFILE functionality? Also, the behavior of DEBUG_OUTFILE has changed between R5 and Domino 6; how does it work now?
Solution:
In Notes/Domino 6, functionality has been added to allow console logging to be dynamically started or stopped.
Supporting Information:
The previous implementation of DEBUG_OUTFILE is such that:
1. It is enabled with the NOTES.INI variable DEBUG_OUTFILE=<pathname><file>. If <pathname> was not an absolute path, the file was created in the current (startup) directory.
2. Most console output goes to this file (there are currently some exceptions such as semaphore timeout messages).
We have added the following new features that improve flexibility and enhance our FFDC (First Failure Data Capture) ability. (Note: The term "Debug Outfile" is synonymous with "Console Log"):
1. Logging to the file can be enabled/disabled while the tasks are running.
2. The initial state of logging can be set.
3. Files are named/renamed in a meaningful way.
4. File size limitations can be imposed.
CONSOLE LOG PATHNAME
The Console Log file is always created. The name of the file and the directory are determined by two variables, DEBUG_OUTFILE and LOGFILE_DIR. The logic behind how they are utilized is this:
a. If DEBUG_OUTFILE and LOGFILE_DIR both exist and DEBUG_OUTFILE is a fully qualified path, the server will use DEBUG_OUTFILE to determine the location and name of the console log file. If DEBUG_OUTFILE is just a filename, the server will use that value as the filename, and LOGFILE_DIR as the directory the file will be located in.
b. If only DEBUG_OUTFILE exists, and DEBUG_OUTFILE is a fully qualified path, the server will use DEBUG_OUTFILE to determine the location and name of the console log file. Otherwise, the server will use <datadirectory>\IBM_TECHNICAL_SUPPORT as the directory, and the value of DEBUG_OUTFILE as the file name.
c. If only LOGFILE_DIR exists, the server will use LOGFILE_DIR as the directory and CONSOLE.LOG as the filename.
d. If neither variable exists, the Console Log file will be <datadirectory>\IBM_TECHNICAL_SUPPORT\console.log.
CONSOLE LOG RENAMING
When the Console Log is created, a line is inserted at the top that contains a string consisting of the file type (console), the machine name, and the current time and date. For example: the first line of the console log from the server running on the machine "daisy" would look like:
console_daisy_2002_07_29@12_25_31.log
When the Notes/Domino application starts a new session, the CONSOLE.LOG file is renamed to this string value and a new CONSOLE.LOG file is created. If the file only contains the string, the file is not renamed and saved, but instead is overwritten. On the MAC, filenames are limited to 31 characters, so the machine name is not included.
NOTE: Due to the use of the machine name when renaming the file, if you are running with partitions, you may end up with 2 files with the same name (with only the date/time stamp differing.) In order to prevent this, give the DEBUG_OUTFILE parameter for each server a unique name, such as the short name of the Domino server that is being logged.
CONSOLE LOG INITIAL STATE
The initial state of logging (on/enabled or off/disabled) is determined by the variable CONSOLE_LOG_ENABLED and, for historical reasons, by DEBUG_OUTFILE in order to maintain backward-compatible behavior. So:
a. If the CONSOLE_LOG_ENABLED variable exists, then use it. CONSOLE_LOG_ENABLED=1 will set the initial state to ON, while CONSOLE_LOG_ENABLED=0 will set the initial state to OFF
b. If only DEBUG_OUTFILE exists, the initial state is ON.
c. If neither variable exists, the initial state is OFF.
TOGGLING CONSOLE LOG OUTPUT
Output to the Console Log can be "toggled" on and off during the session by 2 methods:
Method 1
Changing the state of the NOTES.INI variable CONSOLE_LOG_ENABLED. Each time output is sent to the Console the variable is checked (if the NOTES.INI sequence number has changed) and the setting is honored.
Method 2
Server Console commands:
The commands "start consolelog" and "stop consolelog" have been added that will enable/disable output to the outfile. These commands are not sticky; they are in effect only for the current server session.
DOMINO STARTUP MESSAGE
During Domino server initialization a message is printed to the server console indicating the state of Console Logging, for example:
The Console Log file is d:\domino\logs\console.log
Console Logging is ENABLED
DOMINO RUNTIME MESSAGE
If the state of logging changes during runtime, a message is printed to the server console (as appropriate)
Console Logging is DISABLED
Console Logging is ENABLED
This is helpful for the Java Console parsing the output to determine when data was written to the file, as well as informing the administrator of the current state.
CONSOLE LOG FILE SIZE LIMITATIONS
The variable CONSOLE_LOG_MAX_KBYTES is available for controlling log file size. This variable determines the maximum size that the debug outfile can grow to. When the size is reached, the output "wraps" so that new data is written to the beginning of the file, overwriting any previous data. If the CONSOLE_LOG_MAX_KBYTES variable does not exist, or if CONSOLE_LOG_MAX_KBYTES=0, then the file size is unlimited.
CONSOLE_LOG_MAX_KBYTES can be changed at any time during the session. The new setting takes effect upon the next write, with output continuing at the current location and allowing the file to grow to the new maximum. If the variable CONSOLE_LOG_MAX_KBYTES is increased or set to 0 (unlimited) during the session, then the setting takes immediate effect. If CONSOLE_LOG_MAX_KBYTES is less than or equal to the current file size, the maximum size for the session will be set to the current size to prevent growth. The new CONSOLE_LOG_MAX_KBYTES value will take effect for the next server session.
CONSOLE LOG MISCELLANY
- The output toggle feature works even if new tasks are started during the session. If output is toggled off, a new task started, then output is toggled on again, the new task's output will start going to the output file.
- DIRLINKS are not supported for the LOGFILE_DIR location. You must use the path in the NOTES.INI variable only.
- The Console Log is implemented using File Descriptor Groups, which reduces the file descriptor requirement to 1 per process instead of the previous 1 per thread.
- Delayed Console Log closing is still supported so that memory leak messages are still written to the Console Log.
Related Documents:
previous page
|