Chapter 4   Logging Server Messages


This chapter describes the message-logging service provided by iPlanet Application Server.

The following topics are included in this chapter:

• About the Logging Service

• About Web Server Requests

• About DSync Logging Options

About the Logging Service

---

You can enable the logging of server messages using the iPlanet Application Server message-logging service. The logging service is configured through the iPlanet Application Server Administration Tool Logging window. There you can specify the destination and types of messages logged.

When you enable logging, iPlanet Application Server records messages generated by iPlanet Application Server application-level and system-level services. These messages describe the events that occur while a service is running. For example, each time iPlanet Application Server communicates with the database, the logging service records the resulting messages generated by database access service.

Determining Types of Messages to Log

You can log any of the three types of messages generated by iPlanet Application Server services. Each type is described in the following table:

Table 4-1    Log Message Types

Message type	Description	When it might appear
Information message	Describes the processing of a request or normal service activity, such as a status update.	When no problems arise.
Warning message	Describes a noncritical problem that might be an indication of a larger problem.	When a service encounters a temporary problem, such as when it is unable to connect to a process.
Error message	Describes a critical failure of the service, from which recovery is not likely.	When a service encounters a critical problem, such as a pipe closure.

With the logging service, you can record error messages, error and warning messages, or all messages. To choose which type of messages to log, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. Select the Enable Server Event Log checkbox as shown in the following figure:

   
   
   

3. In the General area, from the Message Type drop-down box, select Errors, Errors and Warnings, or All Messages.

4. In the Maximum Entries text field, enter the maximum number of entries that can exist before data is written to the log.

5. In the Write Interval text field, enter the amount of time (in seconds) that elapses before data is written to the log.

Logging Application Messages

Message logging is also useful for tracking and debugging application errors. By using the log( ) method, application developers can send messages to the same log destination the server administrator configures for iPlanet Application Server services.

For example, if an application encounters a problem in a segment of code, you can log the associated error message. Informational messages about the application's status, rather than error messages, are also useful.

How Log Messages Are Formatted

Every log message has the following four components:

• date and time the message was created

• message type, such as information, warning, or error

• service or application component ID

• message text

When a log message sent to the text-based destination logs, it is formatted as follows:

[Date and time of message] Message type: Service ID: Message text

For example, the following messages sent to an ASCII text file illustrate message format:

[01/18/00 11:11:12:0] info (1): GMS-017: server shutdown (host 0xc0a801ae, port 10818, group 'iAS') - updated host database

[01/18/00 11:11:18:2] warning (1): GMS-019: duplicate server (host 0xc0a8017f, port 10818) recognized, please contact iPlanet Communications for additional licenses

Determining the Logging Destination

You can configure the logging service to record server and application messages in any or all of the destinations described in the following table:

Table 4-2    Message Logging Destinations  

Log destination	Description	When to use
Process consoles	The iPlanet Application Server process consoles display log messages as they are generated.	This is the default. If logging is enabled and the server is enabled for automatic startup (UNIX) or interaction with the desktop (NT), the consoles open and display the log messages. You can disable this feature by deselecting the Log to Console checkbox.
Application log	The default application log file. For Windows NT, this is viewable through the Event Viewer.	This is the default. Provides a more comprehensive record of the server and application error messages. Warning and information messages are not logged to the application log. All messages are sorted by their timestamp.
ASCII text file	An ASCII text file, which you must create and specify.	Use when you want a more permanent record of the server and application messages. All messages are sorted by their timestamp.
Database table	A database table which you must create and specify.	This is the most versatile logging destination. Use when you want to sort, group, and create reports of the logged messages.

When you enable logging, the logging service automatically sends messages to the process consoles on Windows NT and Unix platforms, as long as those consoles are open and console logging enabled. On Windows NT, the logging service also sends messages to the application log. Logging to a process console does not record the messages. You cannot retrieve the messages once they scroll off of the screen.

To enable the logging service and specify the destination of the log messages, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. Select the Enable Server Event Log checkbox.

   
   
   

3. In the Log Target box, choose the type of logging to enable by clicking the desired checkboxes:
   • Log to a Database

   • Log to Windows NT Application Log (Errors Only)

   • Log to File

   You can disable console logging by deselecting the Log to Console checkbox.

   See "Logging to a Database" in the following section and Logging to a File for more information.

   If you chose to log to a file, that file is created now. See Rotating Log Files for information about managing log files.

iPlanet Application Server uses a log buffer to store messages before they are written to the application log, an ASCII file, and/or database logs. This buffer optimizes the performance of the application server by limiting the use of resources to continually update a log. The buffer is written to the destination when either the buffer interval times out or the number of entries in the buffer exceeds the maximum number allowed.

Logging to a Database

If you plan to log application server messages to a database, you need to create an event log database table. The following table describes the four field names and lists each field's data type.

---

Note

On a UNIX system, you can use supplied scripts that automatically set up the eventlog and httplog tables. The scripts are located in the directory $GX_ROOTDIR/APPS/GXApp/Logging/db, and are named Log_db2.sql, Log_ifmx.sql, Log_mssql.sql, Log_ora.sql, and Log_syb.sql. Choose the script that is appropriate for the database you're using.

---

Table 4-3    Logging to a Database Table

Database field name	Description	Data type
evttime	Date and time the message was created	Date/Time
evttype	Message type, such as information, warning, or error	Number
evtcategory	Service or application component ID	Number
evtstring	Message text	Text

The logging service maps the message components to the database fields listed in the table. You must use these exact field or column names in your database table.

To log to database, perform following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. Select the Enable Server Event Log checkbox as shown in the following figure:

   
   
   

3. In the Log Target box, click the Log to Database checkbox.

   Enter the data source, the database name, the table name, and the user name and password necessary for accessing the database.

4. In the General box, from the Message Type drop-down box, select Errors, Errors and Warnings, or All Messages.

5. Click the Apply Changes button to save your changes to iPlanet Application Server Administration Tool.

Logging to a File

iPlanet Application Server Administration Tool's monitoring service allows you to log information about server activity to a file.

To log information to a file, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. Select the Enable Server Event Log checkbox.

3. In the Log Target box, select the Log to File checkbox.

4. In the Log to File text field, enter the name of the log file.

5. In the General box, from the Message Type drop-down box, select Errors, Errors and Warnings, or All Messages.

6. Click Apply Changes to save your changes to iPlanet Application Server Administration Tool.

Rotating Log Files

If you choose to record server messages in an ASCII file, you can enable log file rotation to regulate when log files are rotated. Since log files are stamped with the time and date they are created, log file rotation helps organize log files into manageable units.

To configure log file rotation, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. Select the Enable Server Event Log checkbox.

   
   
   

3. Click the Log to File checkbox.

4. In the Enable File Rotation drop-down box, choose Yes.

5. From the Rotation Interval drop-down box, select the interval at which log files are rotated or enter a string to indicate when the log file is rotated.

   For instance, the following string indicates logging to a new file begins at 1:00 AM every Monday, as well as on the fifteenth of each month:

      1:0:0 1/15/*

   The following string indicates logging to a new file begins at 2:00 AM, 5:00 AM, 6:00 AM, and 7 AM every Friday:

      2, 5 - 7:0:05/*/*

6. In the General area, from the Message Type drop-down box, select Errors, Errors and Warnings, or All Messages.

7. Click Apply Changes to save your changes to the iPlanet Application Server Administration Tool.

About Web Server Requests

---

You can use the iPlanet Application Server logging service to log web server requests. Web server requests are monitored by the web connector plug-in. The plug-in sends requests to your iPlanet Application Server machine where they are processed. By logging web server requests, you can track request patterns and other important request information.

How Web Requests Are Logged

A web server request is divided into components. These components are standardized HTTP variables used by the web server to manage web requests. iPlanet Application Server includes a subset of these HTTP variables for you to log. You can add variables to the list if you need to log additional information.

---

Note	On a UNIX system, you can use supplied scripts that automatically set up the HTTP log and event log tables. See Logging to a Database for more information.

---

Each HTTP variable must be mapped to a database field name within a table that you create. For instance, to log the length of the content of a web server request, map the CONTENT_LENGTH variable to a database field named, for example, content_length and defined as a text data type. The default HTTP variables used by iPlanet Application Server and their database data types are listed in the following table. Use this table to help you create the database table for logging web requests.

Table 4-4    HTTP Variables and Database Data Types

Default HTTP variables	Default database field name	Data type
Not applicable	logtime	Date/Time
CONTENT_LENGTH	content_length	Number
CONTENT_TYPE	content_type	Text
HTTP_ACCEPT	accept	Text
HTTP_CONNECTION	connection	Text
HTTP_HOST	host	Text
HTTP_REFERER	referer	Text
HTTP_USER_AGENT	user_agent	Text
PATH_INFO	uri	Text
REMOTE_ADDR	ip	Text
REQUEST_METHOD	method	Text
SERVER_PROTOCOL	protocol	Text

You must have a field name called logtime in the database table. The time the message is created is assigned by the logging service. The logging service maps that time to the logtime database field. You can rename all of the other database field names.

The fields from the database table are automatically mapped to web server variables in the registry.

You must have a web server communication plug-in module such as NSAPI or ISAPI installed and properly configured. Even though this happens automatically during installation, there may be occasions when you must manually configure the web server.

Logging Web Server Requests

Before you can log web server requests, you must create a database table to hold the request messages. For more information about creating this table, see How Web Requests Are Logged.

To log web server requests, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. From the left pane of the Logging window, select the application server responsible for logging web server requests.

   If you have more than one application server, you can specify one server to log web server requests.

3. In the right pane of the logging window, click the HTTP tab.

   The following window appears:

   
   
   

4. Enter httplog in the Data Source field.

5. Enter the information you use to connect to the database in the Database field. For example, this would be the Oracle SID for an Oracle database.

6. In the Table Name field, enter httplog.

7. Enter the user name and passwords with which you connect to the database. Enter the maximum entries.

   This number represents the greatest number of entries that can exist before data is written to the log.

8. Enter the write interval.

   This number represents the amount of time that lapses before data is written to the log.

9. Click Apply Settings to save your changes to your application server.

About DSync Logging Options

---

iPlanet Application Server supports Distributed Data Synchronization (DSync) across multiple iPlanet Application Server for partitioned and distributed applications. DSync provides cluster management and data synchronization across iPlanet Application Server processes. The iPlanet Application Server Administration Tool provides for logging of DSync messages.

For more information about distributed data synchronization, see

How DSync Messages Are Logged

• DSync provides a component based architecture that allows you to choose which components you want to log. All DSync debug messages appear in KXS, KCS, and KJS log files. DSync debug components are the following:Module: Provides data management and appends other DSync components to the log file. When enabled, the methods executed by DSync are logged.

• Failover: Provides cluster membership management. When enabled, interactions between servers and how roles change due to failure of servers/engines/network connection are logged.

• Token: Provides distributed lock management features. When enabled, interactions between servers for read/write tokens associated with DSync nodes are logged.

• Timeout: Provides life cycle management of DSync nodes per timeout specification. When enabled, nodes that are deleted due to timeout are logged.

• Messenger: Provides message communication between iPlanet Application Server servers. When enabled, messages that are created, sent, received and processed are logged.

In addition, you can dump cluster and DSync node data into iasdsync-cluster-XXX.log and iasdsync-node-XXX.log files respectively where XXX represents the port number of an engine.

Format of the Cluster Dump Files

Each iasdsync-cluster-XXX.log file consists of the following sections:

• Cluster

• Message queue

The cluster information reports how an engine views the current Dsync cluster as follows:

****************************

*DSync Cluster State

***************************

Host: 0xd00c3643

Port: 10818

Role: SyncPrimary

Current Engine's order #:1

SyncPrimary: this engine

Is connect to primary? NO

Changing primary? NO

Max number of SyncBackup#=1

SyncLocal[1]:0xd00c3643:10821

SyncLocal[2]: 0xd00c3643:10822

The message queue information displays the list of messages that are in the DSync queues as follows:

****************************************

*DSync RecvQueue for GXP_DSYNC protocol

****************************************

Message[1]: GXDSYNC_MSG_RECLAIM_RDTOKEN(/dsync41test/K/5)from 0xd00c3643:10818

...

Format of the DSync Node Dump Files

Each iasdsync-node-XXX.log consists of the following sections:

• Message queue

• Node Data

• Timeout Manager

The message queue information displays the list of messages that are in the DSync queues as follows:

****************************************

*DSync RecvQueue for GXP_DSYNC protocol

****************************************

Message[1]: GXDSYNC_MSG_RECLAIM_RDTOKEN(/dsync41test/K/5)from 0xd00c3643:10818

...

The node data section displays the collection of nodes stored in an engine as follows:

****************************

*DSync Token State

***************************

[1] ID:/

   Status: without Read or Write Token

   Scope: GLOBAL

[2} ID:/dsync41test

   Status: without Read or Write Token

   Scope: GLOBAL

   Owner Thread: 0xf6f040 (Id=0xf78d50)

   Standard wait queue[1] thread 0xf88670 (Id=0xf883a0)

   Standard wait queue[1] thread 0xf89d60 (Id=0xf89a90)

   Child[0]:B

   Child[1]:A

   Child[2]:D

   Child[3]:C

   Attribute[NextPath]:N

[3]..

The timeout manager section displays the set of nodes that are managed by DSync timeout manager in the current engine as follows:

****************************************

*Timeout Manager State

****************************************

Entry[0]: ID=/dsync41test/S/4, expired 6 seconds ago

Entry[1]: ID=/dsync41test/U/4, expired 4 seconds ago

Entry[2]: ID=/dsync41test/W/4, expired 3 seconds ago

Entry[3]: ID=/dsync41test/V/4, expired 3 seconds ago

Entry[4]: ID=/dsync41test/X/4, expired 3 seconds ago

Entry[5]: ID=/dsync41test/D/5, expired 2 seconds ago

Entry[6]: ID=/dsync41test/Z/4, expired 2 seconds ago

Entry[7]: ID=/dsync41test/A/5, expired 1 seconds ago

Entry[8]: ID=/dsync41test/B/5, 0 seconds till expiration

Entry[9]: ID=/dsync41test/C/5, 0 seconds till expiration

Entry[10]: ID=/dsync41test/E/5, 0 seconds till expiration

Entry[11]: ID=/dsync41test/F/5, 1 seconds till expiration

Entry[12]: ID=/dsync41test/H/5, 2 seconds till expiration

Logging DSync Messages

To log DSync debug messages, perform the following steps:

1. Click the Logging button on the iPlanet Application Server Administration Tool toolbar to open the Logging window.

2. From the left pane of the Logging window, select the application server responsible for logging DSync messages.

3. In the right pane of the logging window, click the DSync tab.

   The following window appears:

   
   
   

4. Specify the DSync components you want to log as follows:
   • Module: Provides data management and appends other DSync components to the log file. When enabled, the methods executed by DSync are logged.

   • Failover: Provides cluster membership management. When enabled, interactions between servers and how roles change due to failure of servers/engines/network connection are logged.

   • Token: Provides distributed lock management features. When enabled, interactions between servers for read/write tokens associated with DSync nodes are logged.

   • Timeout: Provides life cycle management of DSync nodes per timeout specification. When enabled, nodes that are deleted due to timeout are logged.

   • Messenger: Provides message communication between iPlanet Application Server servers. When enabled, messages that are created, sent, received and processed are logged.

   When specifying DSYNC components, you do not have to shutdown and restart iPlanet Application Server for changes to take affect.

5. Optionally, click Dump Cluster Info to dump DSync state cluster information to a iasdsync-cluster-XXX.log file where XXX is the port number of an engine.

   For information about the format of this log file, see Format of the Cluster Dump Files.

6. Optionally, click Dump Node Info to dump DSync state node information to a iasdsync-node-XXX.log file where XXX is the port number of an engine.

   For information about the format of this log file, see Format of the DSync Node Dump Files.