		BEA WebLogic Enterprise 4.2 Developer Center
		HOME \| SITE MAP \| SEARCH \| CONTACT \| GLOSSARY \| PDF FILES \| WHAT'S NEW
		Administration \| TABLE OF CONTENTS \| PREVIOUS TOPIC \| NEXT TOPIC \| INDEX

Monitoring Log Files

To help you identify error conditions quickly and accurately, the WLE and BEA TUXEDO systems provide you with two log files:

User log (ULOG)-a log of messages generated by the system while your application is running.
Transaction log (TLOG)-a binary file that is not normally read by you (the administrator), but that is used by the Transaction Manager Server (TMS). A TLOG is created only on machines involved in global transactions.

These two logs are maintained and updated constantly while your application is running.

This chapter discusses the following topics:

What is the ULOG?

The user log (ULOG) is a central event logger. All messages generated by the WLE or BEA TUXEDO system-error messages, warning messages, information messages, and debugging messages-are written to this log. Application clients and servers can also write to the user log.

A new log is created every day and there can be a different log on each machine. However, a ULOG can be shared across machines when a remote file system is being used.


This Part . . .	Consists of . . .
tag	A 6-digit string (`hhmmss`) representing the time of day (in terms of hour, minute, and second)
	Name of the machine (as returned, on UNIX systems, by the `uname -n` command)
	Name and identifier of the process that is logging the message
text	Message catalog name
	Message number
	System message

Consider the following example of a user log message.

121449.gumby!simpserv.27190: LIBTUX_CAT:262: std main starting

From the message tag we learn:

The message was written into the log at around 12:15 P.M.
The machine on which the error occurred was gumby.
The message was logged by the simpserv process (which has an ID of 27190).

From the message text we learn:

The message came from the LIBTUX catalog.
The number of the message is 262.
The message itself reads as follows: std main starting.

For more information about a message, note its catalog name and catalog number. With this information you can look up the message in the WebLogic Enterprise System Messages and BEA TUXEDO System Message Manual, which provide complete descriptions of all system messages.

Location

By default, the user log is called ULOG.mmddyy (where mmddyy represents the date in terms of month, day, and year) and it is created in the $APPDIR directory.

You can place this file in any location, however, by setting the ULOGPFX parameter in the MACHINES section.

What is tlisten?

tlisten is the section of the ULOG in which error messages for the tlisten process are recorded. (The tlisten process provides remote service connections for other machines.) As part of the ULOG file, a tlisten log can be viewed with any text editor.

Each machine, including the master machine, should have a tlisten process running on it. Separate tlisten logs are maintained in the ULOG on each machine. However, they can be shared across remote file systems.

Purpose

The tlisten log is a record of tlisten process failures. It is used, during the boot process, by tmboot and, while an application is running, by tmadmin.

How is the tlisten log created?

The tlisten log is created by the tlisten process as soon as that process is started. Whenever a tlisten process failure occurs, an appropriate message is recorded in the tlisten log.

Message Format

Each tlisten log message includes the date and time at which the message was added to the log.

Location

By default, the tlisten log resides in $TUXDIR/udataobj. You can store it in another location, however, by entering the following command.

tlisten -L new_pathname

For example, if you want your TLOG file to be named TLLOG and to reside in the /home/apps/logs directory, enter the following command.

tlisten -L /home/apps/logs/TLOG

What is the transaction log (TLOG)?

The transaction log (TLOG) keeps track of global transactions during the commit phase. A global transaction is recorded in the TLOG only when it is in the process of being committed. The TLOG is used to record the reply from the global transaction participants at the end of the first phase of a two-phase-commit protocol. The TLOG records the decision about whether a global transaction should be committed or rolled back.

We recommend that you create a TLOG on each machine that participates in global transactions.

How is the TLOG created?

For instructions on creating a TLOG, see the section "Creating a Transaction Log (TLOG)" in this chapter.

How is the TLOG used?

The TLOG file is used only by the Transaction Manager Server (TMS) that coordinates global transactions. It is not read by the administrator.

Location

The location and size of the TLOG are specified by four parameters that you set in the MACHINES section of the UBBCONFIG file: TLOGDEVICE, LOGOFFSET, TLOGNAME, and TLOGSIZE. (For descriptions of these parameters and instructions for assigning values to them, see "Creating a Transaction Log (TLOG)" in this chapter.)

Creating and Maintaining Logs

The ULOG is generated by various WLE or BEA TUXEDO system processes; you do not need to create it. The TLOG, however, is not produced automatically; you must create it.

This section provides the following instructions:

How to assign a location for the ULOG
How to create TLOGs

How to Assign a Location for the ULOG

To override the default location for your ULOG file, specify the desired location as the value of the ULOGPFX parameter in the MACHINES section of the UBBCONFIG file. (By default, the value of ULOGPFX is $APPDIR/ULOG.) The value you assign becomes the first part of the ULOG file name.

Listing 16-1 shows how you can override the default setting.

Listing 16-1 Overriding Default Settings in the MACHINES Section of Your UBBCONFIG File

MACHINES
gumby LMID=SITE1
TUXDIR="/usr/tuxedo"
APPDIR="/home/apps"
TUXCONFIG="/home/apps/tuxconfig"
ULOGPFX="/home/apps/logs/ULOG"
...

The following ULOG was created for SITE1 on 04/13/98.

/home/apps/logs/ULOG.041398

Creating a Transaction Log (TLOG)

To create a TLOG, you must complete the following procedure:

This section provides instructions for each step.

Step 1: Assign Values to MACHINES Parameters

Your first step is to assign values to four parameters in the MACHINES section of the UBBCONFIG file: TLOGDEVICE, TLOGNAME, TLOGOFFSET, and TLOGSIZE.

TLOGDEVICE

TLOGDEVICE specifies the device in the BEA TUXEDO file system that contains the transaction log. This can be the same device used by TUXCONFIG.

Note: Technically, there is no reason that TLOGDEVICE cannot be a separate VTOC file, but there are two reasons why it is not recommended: the TLOG is generally too small to justify devoting a raw disk segment to it, and creating TLOGDEVICE as a UNIX file leads to expensive delays when synchronous writes to the TLOG are required.

The TLOG is stored as a WLE or a BEA TUXEDO system VTOC table on the device named in this parameter. If the TLOGDEVICE parameter is not specified, there is no default; the WLE or BEA TUXEDO system assumes that no TLOG exists for the machine. If no TLOG exists for a given machine, the associated LMID cannot be used by server groups that participate in distributed transactions.

After TUXCONFIG has been created via tmloadcf, you must create a device list entry for the TLOG on each machine for which TLOGDEVICE is specified. This is done using the tmadmin crdl command. The BBL creates the log automatically the first time the system is booted.

TLOGNAME

TLOGNAME specifies the name of the Distributed Transaction Processing (DTP) transaction log for this machine. The default name is TLOG. If more than one transaction log exists on the same TLOGDEVICE, each transaction log must have a unique name. If a name is specified, it must not conflict with any other table specified on the configuration.

TLOGOFFSET

TLOGOFFSET specifies the offset in pages from the beginning of TLOGDEVICE to the start of the VTOC that contains the transaction log for this machine. The number must be greater than or equal to 0 and less than the number of pages on the device. The default value is 0.

TLOGOFFSET is rarely necessary. However, if two VTOCs share the same device or if a VTOC is stored on a device (such as a file system) that is shared with another application, TLOGOFFSET can be used to indicate a starting address relative to the address of the device.

TLOGSIZE

TLOGSIZE specifies the number of pages for the TLOG. The default is 100 pages. Once a global transaction is complete, TLOG records are no longer needed and are thrown away. The maximum number of pages that can be specified, subject to the amount of available space on TLOGDEVICE, is 2048 pages. Choosing a value is entirely application-dependent.

Listing 16-2 shows an example of the use of transaction log parameters.

Listing 16-2 Sample Transaction Log Parameters for a Specified Machine

MACHINES
gumby LMID=SITE1
...
TLOGDEVICE="/home/apps/logs/TLOG"
TLOGNAME=TLOG
TLOGOFFSET=0
TLOGSIZE=100
...

Step 2: Create a UDL Entry

Next, create an entry in the Universal Device List (UDL) for the TLOGDEVICE on each machine that requires a TLOG. You can perform this step either before or after TUXCONFIG has been loaded, but you must do it before the system is booted.

To create an entry in the UDL for the TLOG device, complete the following procedure.

On the master machine (with the application inactive), enter the following.
```
tmadmin -c
```

You do not have to create TLOGs on any machine other than the master machine. The WLE or BEA TUXEDO system creates TLOGs on nonmaster machines (as long as a UDL exists on those machines) when the application is booted.

Enter the following command.
```
crdl -z config -b blocks
```
Repeat steps 1 and 2 on each machine of your application that will participate in global transactions.

Note: If the TLOGDEVICE is mirrored between two machines, step 3 is not required on the paired machine.

During the boot process, the Bulletin Board Listener (BBL) initializes and opens the TLOG.

Step 3 (optional): Allocate Space for a New Device on an Existing System

In step 2, you created a new WLE or BEA TUXEDO file system that can be used to hold the TLOG. Sometimes, however, it is necessary to add new devices or space to an existing configuration or to check space usage. You can perform these tasks by running the command.

tmadmin -c

(You can run this command whether or not the system is booted.)

It is possible that the UDL exists on config but does not have sufficient space for the log. To allocate space on a new device to an existing BEA TUXEDO file system, enter the following.

crdl -z config -b blocks new_device

where new_device specifies the full path name for the new device on which space is to be allocated. This command creates a new entry on the UDL and makes the space available for any tables that are created on config. (For example, this procedure can be used for the TUXCONFIG file when there is not enough space for a modified configuration, for allocating a new TLOG, or for increasing the size of the TLOG by deleting an old log and then creating a larger one.) If you are running several commands using the current configuration, it is possible to set the default configuration by entering the default command (d), as follows:

d -z config

If you run this command, you will not need to enter the -z option after each command.

Under rare circumstances, a device does not start at offset 0. This might happen if space has been allocated on a device (less than the entire device) to a BEA TUXEDO file system, and more space on the same device is available to be allocated. In this case, you can allocate the second entry by entering the following command.

crdl -z config -b blocks -o new_device_offset new_device

Here, new_device_offset specifies the offset of the new space being allocated on the device. (Note that the option is a lowercase o.) In this case, since the first entry on the UDL is allocated at offset 0, TLOGOFFSET and/or TUXOFFSET are set to 0, instead of to the offset of the new device. (The WLE or BEA TUXEDO system needs to find the UDL, from which it can determine the offset of other available space.)

A second (and rarer) reason that a device does not start at offset 0 is that a single raw device is shared. This happens, for example, if a UNIX file system is followed by a BEA TUXEDO file system on the same device. (This situation is risky because the raw device must be writable by the WLE or BEA TUXEDO system administrator and it is possible to overwrite the UNIX file system.) If the first entry on the UDL does not start at offset 0 (as in this example), the device offset must be specified everywhere that the device is referenced. To allocate the entry, enter the following command.

crdl -z config -b blocks -o offset -O offset new_device

Here, offset is the offset of the space to be allocated for the BEA TUXEDO file system (UDL and tables). Note that the -o (lowercase o) specifies the offset of the UDL and -O (uppercase O) specifies the offset of the new device space being allocated. Any devices that are created subsequently on this configuration must use both the -o option with the offset of the first entry, and the -O option with the offset of the new entry. (The offset may be 0 if a new device is being specified.) If the first entry on the UDL is not allocated at offset 0, TLOGOFFSET and/or TUXOFFSET must be set to the offset of the first entry. This is the only case in which TLOGOFFSET and TUXOFFSET must be set in the UBBCONFIG file, and the TUXOFFSET environment variable must be set when all BEA TUXEDO application and administrative processes are being run.

To list the current UDL, enter the following command.

lidl -z config

where config was created using the above procedures. If the first entry was created with an offset other than 0, -o offset must be specified in addition to the configuration device. In verbose mode, this command lists not only the space initially allocated for each device entry, but also the amount of free space.

It is also possible to generate a list of the tables on the configuration by entering the following command.

livtoc -z config

Here config was creating using the above procedures. If the first entry was created with an offset other than 0, -o offset must be specified in addition to the configuration device. This command lists the table name, device number, offset within the device, and number of pages for each table. The first two tables are always VTOC and UDL. TUXCONFIG table names are of the form _secname_SECT, where secname is the name of a section in the UBBCONFIG file. The TLOG table name is based on the TLOG parameter in the UBBCONFIG file, and defaults to TLOG. In the rare case in which two applications share a single BEA TUXEDO file system for the TLOGDEVICE, the TLOG parameter must be different for each application.

Note: A BEA TUXEDO system file system is a file that is managed by BEA TUXEDO, which may be located on a raw disk or in an operating system file system. A BEA TUXEDO system file system contains one TUXCONFIG file and one or more TLOG files.

Because the table names for the TUXCONFIG file are fixed, it is not possible for two applications to share the same BEA TUXEDO file system for the TUXCONFIG file.

Step 4: Create the Log

Perform the following steps to create the log.

Make sure you have a TUXCONFIG file. (If you do not, the commands for creating the TLOG will fail.)
Start a tmadmin session by entering the following command.
```
tmadmin -c
```
At the tmadmin command prompt (>), enter the following.
```
crlog [-m machine]
```
where the value of machine is the LMID of a machine, as specified in TUXCONFIG.
Note: The -m option is shown as optional because it can be specified with the default (d) command of tmadmin. If you have not specified a machine with the d command, however, the -m option is required on the crlog command line.

Maintaining a TLOG

TLOGs require little maintenance. This section provides instructions for two common maintenance tasks: reinitializing a TLOG and removing a TLOG:

To reinitialize a TLOG, enter the following.
```
inlog [-yes] [-m machine]
```
The value of machine is the LMID of a machine, as specified in TUXCONFIG.
Be careful when using this command: it will reinitialize the log even if there are outstanding transactions. The result could be inconsistent TLOGs, possibly causing transactions to abort.
To delete a TLOG, enter the following.
```
dslog [-yes] [-m machine]
```
```
The value of machine is the LMID of a machine, as specified in TUXCONFIG.
```
```
If the application is not active or if there are transactions still outstanding in the log, an error will be returned.
```
Note: The -yes and -m options are shown as optional because they can be specified with the default (d) command. If you have not specified a machine with the d command, however, the -m option is required on the inlog and dslog command lines.

Using Logs to Detect Failures

The BEA TUXEDO log files can help you detect failures in both your application and your system. This section provides instructions for analyzing the data in the logs.

Analyzing the User Log (ULOG)

Note: Although application administrators are responsible for analyzing user logs, application programmers may also consult the logs.

It is not unusual for multiple messages to be placed in the user log for a given problem. In general, the earlier messages will better reflect the exact nature of the problem.

Consider the example shown in Listing 16-3. Notice how LIBTUX_CAT message 358 identifies the exact nature of the problem causing problems reported in subsequent messages, namely, that there are not enough UNIX system semaphores to boot the application.

Listing 16-3 Sample ULOG Messages

151550.gumby!BBL.28041: LIBTUX_CAT:262: std main starting 
151550.gumby!BBL.28041: LIBTUX_CAT:358: reached UNIX limit on semaphore ids
151550.gumby!BBL.28041: LIBTUX_CAT:248: fatal: system init function ...
151550.gumby!BBL.28040: CMDTUX_CAT:825: Process BBL at SITE1 failed ...
151550.gumby!BBL.28040: WARNING: No BBL available on site SITE1.
        Will not attempt to boot server processes on that site.

See the WebLogic Enterprise System Messages or BEA TUXEDO System Message Manual for complete descriptions of user log messages and recommendations for any actions that should be taken to resolve the problems indicated.

Analyzing the tlisten Log

Keep the following guidelines in mind as you check the tlisten messages in your ULOG:

A message is placed in the tlisten log every time the log is contacted.
A sequence number is given to every accepted request.
If you cannot boot your application and subsequently cannot find any tlisten messages in your ULOG file, one of the following problems may have occurred:
- The tlisten process may not have been started.
- The tlisten process may be listening on the wrong network address.
  
  To find out whether one of these errors has occurred, check the ULOG file.
  Note: Application administrators are responsible for analyzing the tlisten messages in the ULOG, but programmers may also find it useful to check these messages.

The CMDTUX catalog in the BEA TUXEDO System Message Manual contains the following information about tlisten messages:

Descriptions of all messages
Recommended actions that you (or a programmer) can take to resolve error conditions reported in these messages

Example

Consider the following example of a message in a tlisten log.

042398; 27909;CMDTUX_CAT: 615 INFO: Terminating tlisten process

This message was recorded on April 23, 1998. Its purpose is simply to provide information: the tlisten process is being terminated. No action is required.

Note: This message can be found in the CMDTUX catalog of the BEA TUXEDO System Message Manual.

Analyzing a Transaction Log (TLOG)

The TLOG is a binary file that contains only messages about global transactions that are in the process of being committed. You should never need to examine this file.

If you do need to view the TLOG, you must first convert it to ASCII format so that it is readable. The BEA TUXEDO system provides two tmadmin commands for this purpose:

dumptlog (dl) -z config [ -o offset ] [ -n name ] [ -g groupname ] filename: This command downloads (or dumps) the TLOG (a binary file) to an ASCII file.
loadtlog -m machine filename: This command uploads (or loads) an ASCII version of the TLOG into an existing TLOG (a binary file).

The dumptlog and loadtlog commands are also useful when you need to move the TLOG between machines as part of a server group migration or machine migration.

For more information about these tmadmin commands, see tmadmin(1) in the BEA TUXEDO Reference.

Copyright � 1999 BEA Systems, Inc. All Rights Reserved.
Required browser version: Netscape Communicator version 4.0 or higher, or Microsoft Internet Explorer version 4.0 or higher.
Last update: July 05, 1999.