Oracle® Communications ASAP System Administrator's Guide
Release 7.2
E18879-01
  Go To Table Of Contents
Contents

Previous
Previous
 
Next
Next
 

3 Monitoring and Managing ASAP

This chapter describes monitoring and managing Oracle Communications ASAP.

Overview of Monitoring and Managing ASAP

ASAP provides the following management and monitoring capabilities:

Configuring System Events and Alarms Using Stored Procedures

System events range from informational events to critical error events. When an ASAP client or server generates a system event, the event is transmitted to the Control server which then saves the event. The Control server determines if the event requires an alarm to be triggered. The Control server determines the alarm centers that are mapped to the alarm and the alarm program to call. This alarm program can be a shell script, a UNIX executable, or a Linux executable to send the alarm to email or print.

Figure 3-1 Alarm Process


The Control server also monitors each application process within ASAP. If an application process terminates, the Control server issues an Abnormal Process Termination event that is mapped to a user-defined alarm program. Abnormal Process Termination events are written to both the application diagnostic file and the database.

Each event can be configured to enable or disable a system alarm. Every alarm has an associated alarm level (such as MAJOR, MINOR, or CRITICAL) and Auto Clear flag. The Auto Clear flag specifies that the alarm should be automatically cleared upon generation. If the alarm is configured as non-auto clearing, it is generated every five minutes until you reset it using the asap_utils administrative remote procedure call (RPC) interface (function 60). If configured as auto-clearing, the alarm is generated only once.

For more information on asap_utils, see ASAP Server Configuration Guide.

An alarm can map to up to five alarm centers which trigger alarm programs to alert users of the system alarm. Typically, such alarms can email an administrator, print reports to an alarm center, page a particular individual, or communicate with a network management system.

Configuring Alarm Centers for Alarm Notification and Escalation

Alarm centers can be pagers, email accounts, printers, network management systems, and so forth. Alarm centers are notified of alarms by means of a UNIX program, or shell script.

To create an alarm center, specify the UNIX program, or shell script that ASAP executes when the alarm is generated. For example, assume there are two alarm centers: a general ADMIN center, which receives messages on a printer, and another center called ADMINPGR, which receives pager notifications. To notify these alarm centers, you must develop two shell scripts or programs.

Alarm center information is contained in tbl_alarm_center. Alarm centers are later mapped to system alarms in tbl_system_alarm. If you are defining a system event that does not map to an alarm, proceed to "Configuring System Events".

Use the following stored procedures to define, list, or delete alarm centers:

  • CSP_new_center – Defines an alarm center to which alarm notifications must be sent by the Control server.

  • CSP_list_center – Lists an alarm center definition from the control database.

  • CSP_del_center – Deletes an alarm center definition from the control database.

For more information on these stored procedures and tbl_alarm_center, refer to the ASAP Developer's Guide.

Configuring System Alarms

System alarms identify system events, such as component malfunction. System events can be mapped to operations which enable, disable, or log alarms.

Alarms in ASAP can be routed to multiple alarm centers, based on the time of day.

The types of alarms that can be configured in ASAP are:

  • Continuous alarm – The continuous alarm is issued periodically until your system administrator manually disables it or ASAP issues a system event to disable the alarm.

  • Single initiation alarm – The single initiation alarm is generated once each time the system event is issued.

Table 3-1 lists and describes alarms and what action is required in response to the alarm.

Table 3-1 System Alarms

Alarm Action

Abnormal Process Termination

This alarm indicates that a component of ASAP has shut down. You can immediately save the log file and take the appropriate steps to restart the process.

General System Error

This is a general purpose system alarm. The description of the error from the ASC_event() call should give sufficient details of the error. If ASAP is otherwise running properly, you can simply note this alarm and deal with it at a convenient time.

General System Warning

A general warning event, not an error situation. This event can be used to indicate errors or exceptions in external systems, for example, Port Bind Failure, Network Element (NE) in Maintenance Mode, and Stored Procedure Deadlock Victim. You can note this alarm and deal with it at your convenience.

General System Information

System information such as thread spawning, process startup, and graceful shutdown, work order (WO) time-outs, Host CLLI in Busy State, etc. These alarms typically do not require user intervention.

Process Termination Error

This error is generated by an application process whenever an internal condition is encountered. This causes the application process to log the system event in the database and then terminate the application process in an orderly manner. This is a critical error. You must immediately determine the problem and restart the process.

Operating System Disk File Error

This is a critical error. This error is generated when an error is encountered when creating, reading, or writing an operating system file. For example, the Network Element Processor (NEP) is unable to create a file to insert the NE response log, and the Service Request Processor (SRP) is unable to create a file for WO completions. You must deal with this alarm immediately.

Critical Database Resource Error

This can be a serious error. The event is issued by inv_rpc() and other RPC calls if a database or transaction log is full, the database is corrupt, etc. You must attend to this alarm immediately, although you can continue to use the system.

Invocation Application Remote/Registered Procedure Failed

This alarm is issued if the RPC or registered procedure fails. The text in the ASC_event() gives the invocation details. If ASAP is otherwise running properly, you can note this alarm and address it at your convenience.

UNIX System Call Error

This is a critical error that is issued if an application encounters a UNIX system call error. You must deal with this alarm immediately.

Application Network Error

This is a serious error. (Unable to connect to the SQL/ Application server, connection to server goes down, etc.). You should save the log file immediately and deal with this situation.

Open Server Application Object Access Error

This error is issued if ASAP is unable to create, remove, lock, unlock, or access Open Server object (Mutex, message queue, etc.). If ASAP is otherwise running properly, you can note this alarm and deal with it at your convenience.

Work Order In Progress Longer Than Specified Threshold

System information event. Indicates that a WO has been in progress longer than a specified threshold time. The description of the error from the ASC_event() call provides information on the error. If ASAP is otherwise running properly, you can note this alarm and deal with it at your convenience.

Work Order Routing Error

This error is generated when the Service Action Request Manager (SARM) is unable to correctly determine the Host NE to which a WO should be routed. The description of the error from the ASC_event() call provides the routing data (Directory Number (DN) or MCLI ). Updates to the routing tables are required.

Network Element Has Gone Into Maintenance Mode

An informational alarm. This alarm is generated when an NE enters maintenance mode. If the alarm persists, investigate the reason.


Each system event can be optionally mapped to a system alarm in tbl_system_alarm.

You can specify the system alarm level: MINOR, MAJOR, or CRITICAL. Each alarm is either self auto-clearing or non-auto-clearing, and may or may not define one or more alarm centers to which the alarm is to be transmitted.

If the alarm is configured as non auto-clearing, it is generated every five minutes until you reset the alarm. If the alarm is configured as an auto-clearing alarm, it is only generated once.

After you have defined the alarm centers for the system, you can define the alarms. An alarm code is used to identify uniquely each alarm in ASAP. You can configure an alarm level for each alarm and up to five different alarm routes. The alarm routes are used to specify daily time intervals for an alarm to be generated at up to five alarm centers and to specify the time period in minutes between a regeneration of the alarm.

Use the following stored procedures to define, list, or delete system alarms:

  • CSP_new_alarm – Defines an alarm within ASAP, and optionally, the associated “alarm code” that may be associated with the event.

  • CSP_list_alarm – Lists system alarm codes and their definitions.

  • CSP_del_alarm – Deletes a system alarm code.

For more information on these stored procedures and tbl_system_alarm, refer to the ASAP Developer's Guide.

Configuring System Events

In ASAP, each application can generate system events from within the application code. In addition, you can configure system events to generate an alarm in certain circumstances [for example, Common Service Description Layer (CSDL) failure, SARM to SRP notifications, database, and file system thresholds being exceeded, and so on] using certain static tables within ASAP.

Each system event is configured in the control database and can be mapped to a particular system alarm. Each alarm can, in turn, be mapped to one or more alarm centers. Each alarm center can then execute a user-supplied alarm program to perform the relevant user-determined alarm notification.


Note:

You can define system events in custom code. The system events you define do not have to be mapped to core system events. To generate alarms, ensure that the event you have defined is mapped to an alarm in the Event/Alarm Configuration function.

Defining System Events

Core and customer-specific subsystems can generate system events. System events are defined in the control database table tbl_event_type.

Events can be associated with an alarm code. In addition, the event can enable or disable the alarm.

Use the following stored procedures to define, list, or delete system events:

  • CSP_new_event – Defines an event type within ASAP, and optionally, the associated “alarm code” that may be associated with the event.

  • CSP_list_event – Lists database threshold definitions.

  • CSP_del_event – Deletes a database threshold definition.

For more information on these stored procedures and tbl_event_type, refer to the ASAP Developer's Guide.

Setting Database Thresholds

The Control server monitors database and transaction log sizes during normal operation. You must configure the database and transaction log thresholds for each database and ASAP environment and the system events that trigger an alarm. When the threshold is exceeded, ASAP can issue the system event to trigger an alarm.

Use the following stored procedures to define, list, or delete database thresholds:

  • CSP_new_db_thresh – Defines database and/or transaction log thresholds to be used by the Control server.

  • CSP_list_db_thresh – Lists database threshold definitions.

  • CSP_del_db_thresh – Deletes a database threshold definition.

Database thresholds are defined in tbl_db_threshold.

For more information on these stored procedures and tbl_db_threshold, refer to the ASAP Developer's Guide.

Sample Alarm Program - admin.sh

The ASAP_Home/scripts/admin.sh sample script is a UNIX shell script. In this example, the admin.sh and adminp.sh scripts are linked copies of each other. Alarm scripts can also be a UNIX executable program. You must copy this script from the ASAP_Hhome/scripts folder to the ASAP_Home/programs folder in order for a control server alarm center to use it.

System events can be issued for critical, major, and minor system errors, system warnings, and system information.

#
# SCCS Id: @(#) admin.sh 1.1@(#)
#
# Script to perform alarm notification.
# 
#
# Note that this script should be placed in the $PROGRAMS directory in order
# for the Control Server to pick it up.
#
TMPFILE=/tmp/alarm.$$
PERMFILE=$LOGDIR/ASAP_Alarm_log
USR=oper1
DEVICE=console
while getopts i:n:e:E:d:f:l:a:s: c
do
case $c in
i) event_id=$OPTARG;;
n) alarm_name=$OPTARG;;
e) event_code=$OPTARG;;
E) event_desc=$OPTARG;;
d) event_text=$OPTARG;;
f) source_file=$OPTARG;;
l) source_line=$OPTARG;;
a) level=$OPTARG;;
s) application=$OPTARG;;
\?) ;;
esac
done
shift `expr $OPTIND - 1`
echo "\n\
*************************************************************************\n\
ASAP Alarm Issued @ `date` \n\
Alarm Program = $0\n\
*************************************************************************\n\
\n\
Arguments:\n\
Event Id = $event_id\n\
Alarm Name = $alarm_name\n\
Event Code = $event_code\n\
Event Desc = $event_desc\n\
Event Text = $event_text\n\
Source File = $source_file\n\
Source Line = $source_line\n\
Alarm Level = $level\n\
Application = $application\n\
\n\
Additional Parameters = $*\n\n\
** End of Alarm **\n" > $TMPFILE
case `basename $0` in 
"admin.sh") cat $TMPFILE >> $PERMFILE
break;;
"adminp.sh") cat $TMPFILE | mail $USR
cat $TMPFILE | write $USR $DEVICE
cat $TMPFILE >> $PERMFILE
break;;
esac
rm -f $TMPFILE
exit 0

If the script name is admin.sh, the alarm message is appended to the alarm log file. This alarm program is only called for minor errors, and therefore does not have to be sent to the users immediately.

If the script name is adminp.sh, the alarm message is appended to the alarm log file, written to oper1 on the system console and mailed to oper1 as well. This alarm program sends a beep to the console and is only called for major alarms such as a process crashing.

Sample Alarm Output

This section contains sample alarm output.

**************************************************************************
ASAP Alarm Issued @ Wed Aug 7 21:00:29 ADT 2002 
Alarm Program = /ASAP/PRODUCTION/programs/adminp.sh
**************************************************************************
Arguments:
Event Id  = 71457
Alarm Name = ABNORMAL
Event Code = ABNORMAL
Event Desc = Abnormal Process Termination - Application
Event Text = Warning: Abnormal Termination of Process LU62SEND
Source File = process.c
Source Line = 701
Alarm Level = CRITICAL
Application = CONTROL

Additional Parameters = 
** End of Alarm **

The output specifies the time and date of the alarm, the script called by the alarm, together with the following information:

Table 3-2 Alarm Output

Alarm Name Description

Event ID

Unique ID for the event that generated the alarm.

Alarm Name

Alarm code associated with the system event.

Event Code

ASAP event generated by the application.

Event Desc

Brief description of the event.

Event Text

Brief description of the reason for the system event within the source code.

Source File

Line in the source file where the event was generated.

Source Line

Source file name where the event was generated.

Alarm Level

Possible values: MINOR, MAJOR, or CRITICAL.

Application

Logical name of the ASAP application server that generated the system event


Sample Alarm Program - POTS Cartridge Sample Code

ASAP provides a working sample cartridge that you can install if you select the POTS Service Activation Model installation option. This cartridge contains the ASAP_Home/samples/sadt/DemoInstall/Nortel/DMS/POTS/control/PLSQL/demo_control.sql script that populates alarm definitions and creates an alarm center mapped to the ASAP_Home/programs/control_prog script. The ASAP installer automatically runs the demo_control.sql script if you select the POTS Service Activation Model installation option.

The alarm center created by the demo_control.sql script runs the control_prog script when it received an alarm or event notification. The control_prog script creates an alarm log file located in ASAP_Home/DATA/logs/ControlProgramOutput that records the alarm output.

Understanding Default System Events

The static table tbl_event_type contains the system events that the ASAP application can generate and, if required, the system alarm code associated with that event. You can modify existing system events in this table or add custom events.

For information on adding alarms and events, see "Configuring System Alarms" and "Configuring System Events".

Each system event must have a record in tbl_event_type.

The following tables contain the system events that are contained in tbl_sys_event and are generated by the application. You can update the static text, alarm level, and description of these system events and add custom events.

API System Events

Table 3-3 lists and defines the system events included in the core application programming interface (API).

Table 3-3 Core API System Events

Event Static Text Alarm Level Description

ABNORMAL

Abnormal process termination as the application process terminated unexpectedly.

Critical. Non auto-clearing.

Event issued by the Control server if any process (server or client) it monitors has terminated unexpectedly.

DISK_ERR

Operating system disk file error.

Critical. Auto-clearing.

Event issued when an error is encountered creating, reading, or writing an operating system file.

NTWK_ERR

Application network connection error.

Minor. Auto-clearing.

Unable to connect to SQL/Application server, connection to server gone down, etc.

RPC_ERR

Invocation of application remote/registered procedure failed.

Minor. Auto-clearing.

Event issued if RPC/Reg Proc fails. The text in ASC_event() gives the invocation details.

RPCSPACE

Critical database resource error.

Critical. Non auto-clearing.

Event issued by inv_rpc() and RPC calls if the database full, transaction logs full, database corrupt, etc.

SRVOBJER

Open Server Application object (Msg Queue, Mutex, etc.) access error.

Minor. Auto-clearing.

Unable to create, remove, lock, unlock, or access Open Server Object (Mutex, message queue, etc.).

SYS_ERR

General system error.

Major. Auto-clearing.

General purpose system error. The description of the error from the ASC_event() call gives sufficient details of the error.

SYS_INFO

General system information notification.

None.

System information such as thread spawning, process startup, and graceful shutdown, WO Timeouts, Host CLLI in Busy State, and administrative flushing of data from memory.

SYS_TERM

Process termination event.

Critical. Auto-clearing.

This event is called by an application process when an internal condition is encountered. The event causes the application process to log the system event in the database and then terminate the application process in an orderly manner.

SYS_WARN

General system warning.

Minor. Auto-clearing.

Warning event, not an error situation. This event can be used to indicate errors or exceptions in external systems, for example, Port Bind Failure, Host LU6.1/LU6.2 Bridge Down, NE in Maintenance Mode, and Stored Procedure Deadlock Victim.

UNIX_ERR

UNIX system call error.

Minor. Auto-clearing.

Event issued if application encounters UNIX system call error. For example, the NEP is unable to create a file to insert the NE response log or the SRP is unable to create a file for WO completions


SARM System Events

Table 3-4 lists and describes the events that the SARM can issue.

Table 3-4 SARM System Events

Event Static Text Alarm Level Description

ROUT_ERR

WO routing error.

Major. Auto-clearing.

Notifies when the SARM process is unable to determine the correct NE to which a particular WO should be routed. The routing data (MCLI or DN) is included in the event text.

WOINPROC

WOs in progress longer than specified threshold.

Informational. Determined by individual customer.

Informs when one or more WOs are in progress for more than the specified threshold time.


Control Server Events

Table 3-5 lists and describes the events that the Control server can issue.

Table 3-5 Control Server Events

Event Description

APP_ERR

ASAP application start-up error.

APP_STRT

ASAP application local or remote start-up.

APP_STOP

ASAP application local or remote shutdown.


NEP System Events

Table 3-6 lists and describes the events that the NEP can issue.

Table 3-6 NEP System Events

Event Static Text Alarm Level Description

BIND_ERR

Port binding error event.

Minor. Auto-clearing.

Unable to allocate device to connect to NE if, for instance, the maximum number of connections to the NE is exceeded. Each device in ASAP has a command processor thread that is always running. When there is a connection request for an NE, the session manager tries to obtain an enabled and unbinded (available) device. If the session manager cannot obtain such a device, the session manager will throw a BIND_ERR event.

CONN_ERR

NE connection error event.

Minor. Auto-clearing.

NE connection attempt failed.

DIAL_ERR

Dialup error event.

Minor. Auto-clearing.

The dial-up program to connect to NE has failed. After a connection is established to a dialup type device, but before the NE_LOGIN (or LOGIN) is performed, a state table named DIALUP is executed. If the DIALUP state table fails, then DIAL_ERR event is thrown.

LOGN_ERR

Login error event.

Major. Auto-clearing.

The login program to the NE has failed. The LOGIN state table is executed after NE connection is established, or, for dialup type devices, after the DIALUP state table has executed. If the LOGIN state table fails, this event is thrown.

MAINTNCE

Host NE has gone into Maintenance mode.

Informational. Determined by individual customer.

Informs when NE enters Maintenance mode.

When the current Atomic Service Description Layer (ASDL) ends with MAINTENANCE exit type, then this event is thrown.

PORT_DIS

Port disabled upon connection failure event.

Major. Auto-clearing.

Connection to NE failed, port/device disabled.

During connection, the NEP tries to connect to the NE. If this connection attempt fails, then the PORT_DIS event is thrown. At the same time, the port or device is disabled. After the PORT_ENABLE_TIMER (a configuration variable defined in ASAP.cfg) has concluded, the port is automatically enabled. Consequently, the same port will not be tried for the second connection attempt while it is disabled. Another port is selected.

You can disable a port (triggering a PORT_DIS event) using asap_utils option 31 (see ASAP Server Configuration Guide for more information). The port is disabled after the currently executing ASDL is completed (for example, in any state like SUCCEED(104), FAIL(253) and so on). After this ASDL completes, the device disconnects from the NE and the port is disabled. Any subsequent ASDLs is provisioned with other available ports and devices.


Configuring and Reading Log and Diagnostic Files

There are two sets of files maintained by ASAP applications for monitoring and troubleshooting purposes: log files and diagnostic files. These files are created by ASAP daily or whenever an application starts up.


Note:

If you write to diagnostic or log files while ASAP is running, you will cause the associated ASAP application to malfunction.

Figure 3-2 shows the sources of log and diagnostic information.

Figure 3-2 Source of Diagnostic Information

This graphic shows the sources of diagnostic information.

About Log Files

Log files contain high-level error messages. These files are created by ASAP daily or whenever a server starts up. Log files are located in the directory $LOGDIR (where $LOGDIR is $ASAP_BASE/DATA/logs) under appl_name.log, where appl_name is the appropriate client or server application.

Every diagnostic call made in ASAP has an associated diagnostic level denoting the importance of the diagnostic message. A specific diagnostic level is also applied to every application process so that only messages with a level greater than, or equal to, the configured level are written to the diagnostic file. This arrangement facilitates the configuration of the diagnostic logging without recompiling the application. For more information on diagnostic levels, see "Server Diagnostic Levels".

Every application executes with the diagnostic level specified in the Application Process Table. The diagnostic level of an application server can be modified dynamically while the server is running by means of an administrative RPC sent using the asap_utils RPC interface.

About Diagnostic Files

Diagnostic files include all low-level activities for each application. These files are created by ASAP daily or whenever a server starts up. Diagnostic files are located in the directory $LOGDIR/yyyymmdd under the name appl_name.diag. where yymmdd is the date for which you want to view the diagnostics and appl_name is the appropriate client or server application.

The diagnostic file rolls over to a new file whenever the maximum diagnostic file size is reached. This file size is configurable using the MAX_DIAG_FILE configuration parameter. You can also configure the number of diagnostic files to be created. This field, together with the maximum file size, limits the amount of disk space that may be used by diagnostic files. When the file limit is reached, the API closes the existing file and opens a new one.

The value of the MAX_DIAG_FILE parameter may depend on the level of diagnostic messages written by the application and the available disk space.

Using ASAP Diagnostic Tools

The diag_filt and diag_filt1 scripts are diagnostic tools contained in the $SCRIPTS directory allow you to view the diagnostic files to filter out the diagnostic messages from a particular thread. You can use this feature to follow the operation of just one thread. Usually, however, it is the interaction of multiple threads with each other that is of most interest to programmers.

diag_filt diagnostic_file thread_number [thread_number ...] > output_file

where:

diagnostic_file is the name of the diagnostic file.

thread_number is the thread number

output_file is the name of an output file

For example, to filter out the diagnostic messages of thread number 7 and 21 from the SARM.diag file and insert the result into the 7_21.out file, enter the following:

diag_filt SARM.diag 7 21 > 7_21.out

Configuring and Reading WebLogic-based Log and Diagnostic Files

ASAP uses log4j to generate and manage the log messages from ASAP's WebLogic components. It does not affect any logs generated by ASAP's C-based (SARM, NEP, Control (CTRL) server) components. The generated log messages are stored in the asap.log file located in WebLogic_domain.

Through the use of log4j, you can develop and maintain a logging strategy that minimizes the overall impact of logging operations on the application's resources. log4j does this by letting you control the volume of log messages generated.

You also have the ability, when necessary, to dynamically change the level and detail of the logged messages. This feature helps you to, for example, increase the level and detail of logged messages to help analyze performance problems within a production environment.

To read more about log4j, refer to Apache Web site:

http://logging.apache.org/log4j

Defining Severity Levels

To control the volume of log messages generated and written to the output destinations (the console and the WebLogic log file, which are referred to as Appenders by log4j), you assign severity levels to the various areas of the application that generate their own, discreet messages (these areas are referred to as Categories by log4j. If an event occurs inside a given category that triggers a message below the severity level assigned to the category (that is, less severe than the assigned level), log4j does not generate the message.

Example

If you assigned the severity level Warning to a given category, log4j does not generate any messages for that category that are flagged in the ASAP code as Debug or Info level messages. log4j will, however, generate all messages that are flagged as Warning, Error, and Fatal.

You can further control the number of messages written to the output destinations, or Appenders, by also assigning a severity level to them. When you assign a severity level to an Appender, it rejects messages below that severity level, even if log4j passes the message to it.

Example

If you configure the console to the Warning severity level, and one of the Categories is configured with the Info level, the console will not display the Info message, even though log4j generates the message and passes it on to the console, because the message's severity level falls below the threshold for which the Appender is configured. If, however, that same Category later generates an Error level message, the console will accept and display the message, because it carries a severity level equal to or higher than the console's threshold.

By default, the console and the WebLogic log file accept all error messages, from the least severe to the most severe.

The Levels

The following is an ascending list of the severity levels, starting with the least severe:

  • Debug – (Least severe) Designates fine-grained informational events that are most useful to debug an application

  • Info – Designates informational messages that highlight the progress of the application at coarse-grained level

  • Warning – Designates potentially harmful situations

  • Error – Designates error events that might still allow the application to continue running

  • Fatal – (Most severe) Designates very severe error events that will presumably lead the application to abort

Configuring the Severity Levels

There are two methods by which you can configure the severity levels:

  • log4j.xml – The log4j.xml file is located in asap$ENV_ID.ear:APP-INF/lib/asaplibcommon.jar. This method allows you to modify the log4j configuration (like log message format, name of the log file, volume of the log files, how many are saved, and so on) and requires you to stop, then restart the servers before the changes will to take effect. For more information, see "Configuring the log4j.xml File".

  • log4jAdmin – The log4jAdmin Web page lets you to dynamically change the severity levels while the servers are running. The changes take effect immediately. As the changes are persisted to the database the severity levels remain at the new level when you restart the server. For more information, see "Using the log4jAdmin Web Page".

The logging levels configured in the database take precedence; all other configuration is controlled by the log4j.xml configuration file embedded inside asap$ENV_ID.ear:APP-INF/lib/asaplibcommon.jar.

Configuring the log4j.xml File

Use this method to modify the log4j configuration as described in "Configuring the Severity Levels". To change the log4j configurations later, you must stop the server, modify the log4j.xml file, then restart the server. In most cases, therefore, if you need to modify the logging levels, you should use the log4jAdmin Web page, as described in "Using the log4jAdmin Web Page".

There are two sections of the log4j.xml file that you need to look at when configuring this file:

  • Appenders – This section defines the output destination for the messages. At installation, the Appenders section contains two entries:

    • Console – From this entry, you control the level of messages that the WebLogic console accepts.

    • WebLogic – From this entry, you control the level of messages that the WebLogic log file accepts.

  • Categories – This section contains references to all of the ASAP categories that generate messages and gives you the ability to control the level of messages they generate.

To configure the log4j.xml file:

  1. Unpack the asap.ear or the srt.ear file, depending on the application for which you are configuring logging parameters.

    • The asap.ear file is found in the $ASAP_BASE/lib directory. After the .ear file is unpacked, unpack APP-INF/lib/asaplibcommon.jar. The log4j.xml file is located in the root directory.

    • The srt.ear files is found in the $ASAP_BASE/SRT/lib directory. After the .ear file is unpacked, unpack APP-INF/lib/asaplibcommon.jar. The log4j.xml file is located in the root directory.

  2. In the Appenders section of the log4.xml file, search for the following string, which appears at the top of the Appenders section:

    <!-- Append messages to the console -->
    

    The Console entry governs what level of messages are written to the console.

  3. If necessary, change the threshold level. By default, it is configured to DEBUG, allowing the console to display all messages sent to it. If you want to restrict the number of messages displayed, change the threshold entry to the severity level appropriate for your installation (see "Severity levels" above, for a description of the severity levels).

    In the example below, the level is changed from DEBUG to INFO.

    Before

    <param name="Threshold" value="DEBUG"/>
    

    After

    <param name="Threshold" value="INFO"/>
    
  4. In the Appenders section, search for the following string:

    <!-- Append messages to the weblogic's log file-->
    

    The Weblogic log file entry governs what level of messages are written to the WebLogic log file.

  5. If necessary, change the threshold level as described in Step 3.

  6. Go to top of the file and search for the following string:

    category name
    

    This takes you to the first category entry in the file.

  7. Review each of the categories in this section, changing the severity level where necessary. In the example below, the level is changed from INFO to WARNING.

    Before

    <category name="com.mslv.system"> <priority value="info"/> </category>
    

    After

    <category name="com.mslv.system"> <priority value="warning"/> </category>
    
  8. When you finish updating the categories, save and close the log4j.xml file.

  9. Repack the .ear file.

  10. Redeploy the .ear file:

    • For Java Service Request Processor (JSRP):

      In $ASAP_BASE/lib, run the following commands:

      ModDeployDescriptor -u <WebLogic Admin Id>
      java weblogic.Deployer -adminurl http://$WLS_HOST:$WLS_PORT
      -user $WLS_USER -password $WLS_PASSWORD -name asap$ENV_ID -remove
      java weblogic.Deployer -adminurl http://$WLS_HOST:$WLS_PORT 
      -user $WLS_USER -password $WLS_PASSWORD -upload 
      -source $ASAP_BASE/lib/asap$ENV_ID.ear -name asap$ENV_ID 
      -targets $TARGET_WLS_SERVER -activate
      
    • For SRT:

      In $ASAP_BASE/SRT run the following commands:

      ant -f install.xml undeploy
      ant -f install.xml deploy
      

Using the log4jAdmin Web Page

Use log4jAdmin Web page to check the current logging levels or to change the logging levels dynamically.


Note:

You can only use this method to change the severity levels of the Categories. To change the Appender's levels, you must reconfigure the log4j.xml file. See "Configuring the log4j.xml File" for an explanation of the Categories, the Appenders, and how to configure the XML file.

The changes you make to the logging severity levels using this method are persisted to the database in the table tbl_code_list on the Control server.


Note:

Because log4jAdmin is bundled with the core, it shares the core session timeout configuration.

Checking the Current Logging Levels

You can use the Filter Loggers feature at the top of the page to check the logging level of specific categories or subcomponents. If you know the name of the category or subcomponent that you want to check, you can use the filter to display only that category, or related, categories.

To check logging levels:

  1. Open the log4jAdmin Web page by entering the following path in the browser's address line (the URLs are case sensitive):

    • JSRP:

      http://BEA_HOST:BEA_PORT/ASAP_ENVID/log4jAdmin.jsp
      

      or

      https://BEA_HOST:BEA_SSL_PORT/ASAP_ENVID/log4jAdmin.jsp
      
    • SRT:

      http://BEA_HOST:BEA_PORT/ASAP_ENVID/SRT/log4jAdmin.jsp
      

      or

      https://BEA_HOST:BEA_SSL_PORT/ASAP_ENVID/SRT/log4jAdmin.jsp
      
  2. In the Filter Loggers field, enter the beginning of the name or a part of the name.

  3. Do one of the following:

    • Click Begins With to filter on the beginning of the name.

    • Click Contains to filter on part of the name.

      The list displays the categories and subcategories that match the entry in the Filter Loggers field.

    • (Optional) To change the logging level do the following:

      1. Scan the entries in the left-hand column and find the category or sub-component which you want to change.

      2. Scan across the row to the severity levels. The level that currently is selected is highlighted in a different color from the other levels and appears in the Effective Level column.

      3. Click the logging level which you want to change:

        To change an entire category, click the category name.

        To change the subcomponent, click the sub-component name.

        The change takes place immediately.

      4. When you finish making the changes, close the page.

Enabling Stored Procedure Error Messages

To enable stored procedure error messages for a sqlplus session, use the following procedure:

  1. From a UNIX terminal, source your ASAP ASAP_home/Environment_Profile.

    . ./Environment_Profile
    
  2. Log into your sqlplus session for the database you want to run stored procedures on. For example:

    sqlplus $CTRL/password
    

    Where password is the password for your ASAP server database schema.

  3. Run the following command to enable stored procedure error messages.

    set serveroutput on;
    

    For an error message example, see the following error message in bold:

    var retval number; 
    exec :retval := SSP_new_comm_param('T', 'TEL_HOST','COMMON_DEVICE_CFG','HOST_USERID','asapXXX','userid'); 
    Host TEL_HOST For Device Type T And Parameter HOST_USERID Does Not Exist, No 
    Comm Param Inserted. 
    . 
    PL/SQL procedure successfully completed. 
    . 
    SQL> print retval; 
    . 
        RETVAL 
    ---------- 
             0