SIP Servlet Engine© Documentations
 
  Top >   System Administration >   Configuration >   Logging Management
 
 

Logging Management

For logging, the jakarta Log4j library is used. In SIP Servlet Engine, the following three types of log can be recorded: execute log, application log, and SIP access log. In addition, the contents of the execution log to the console from which the server was started can be output to standard output and system log (syslog) as well.

Types and Contents of the Log

Execution Log

Execution log records the logs of SIP Servlet Engine, Service Provider Interface (SPI) and the basic components.

The execution log records the internal state of a server and its operational information. This information may be required upon occurrence of a failure.

Settings for log output before shipping

Output file name logs/sip-engine.log
Maximum file size 3,000KB
Number of generations backed up 10000
Output format Date and time {ISO8601} Output level Hierarchy category [Thread name]{Tab}: Output message {Linefeed}
Contents of output SIP Servlet Engine(com.oki.sip.*) log - info level
Library (org.apach.*) log - warn level
SIP application log - info level

Sample output 

 2004-11-09 10:19:50,398 INFO  ServerConfig    [Main Thread]     : Loading server conf file: "sipserver.xml"
 2004-11-09 10:19:50,844 INFO  LicenseManager  [SipLicenseWatcher]       : Starts license file watcher.
 2004-11-09 10:19:50,886 INFO  LicenseManager  [Main Thread]     : Loading license file (/usr/local/bea/sip-license.xml).
 2004-11-09 10:19:50,972 INFO  ConnectorManager [Main Thread]    : Installed connector: host="172.28.213.96", port="5060", transport="udp"
 2004-11-09 10:19:50,979 INFO  ConnectorManager [Main Thread]    : Installed connector: host="172.28.213.96", port="5060", transport="tcp"
 2004-11-09 10:19:51,008 INFO  SessionManager  [Main Thread]     : Set session swap out duration: "600000" ms.
 2004-11-09 10:19:51,021 INFO  ProxyManager    [Main Thread]     : Set proxy: host="siplb.cs.oki.co.jp", port="5060", transport="udp"
 2004-11-09 10:19:51,034 INFO  ProxyManager    [Main Thread]     : Request transfer policy: domain,proxy

Application Log

An application log is deployed on SIP Servlet Engine and recorded by an operating SIP application.

The application log is recorded when an application has used a method for logging (Servlet.log method) and when the system has received an exception thrown while an application is running (except for when the exception was handled within the application).
In a system for development, an application developer can use the application log for debugging. In an operational system, the system administrator can use the application log for monitoring, in order to detect application-level failures.
With an application in operational phase, it is recommended to output only the important logs so as to avoid degradation of the system performance.

Settings for log output before shipping

Output file name logs/sip-application.log
Maximum file size 3,000KB
Number of generations backed up 10000
Output format Date and time {ISO8601} Output level Hierarchy category [Thread name]{Tab}: Output message {Linefeed}
Contents of output SIP application log - info level

Sample output 

 2004-11-08 22:43:26,657 INFO  /sip-demo [Main Thread] : init
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : Servlet name: proxy
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : record-route=[true]
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : parallel=[true]
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : supervised=[true]
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : recurse=[false]
 2004-11-08 22:43:26,659 INFO  /sip-demo [Main Thread] : redirectURL=[http://wpc3238.cs.oki.co.jp:7001/sip-demo/open/redirectRecorder.jsp]

SIP Access Log

The SIP access log records all the SIP messages received at SIP Servlet Engine.

With a Web server, the messages received are limited to HTTP requests, but with a SIP server, SIP requests and SIP responses are both received.
In a system for development, an application developer can use the access log to check how external SIP requests and SIP responses are received at SIP Servlet Engine. In addition, by outputting distinguishable information of SIP dialogs such as Call-IDs from he application log and extracting relevant SIP messages from the access log, the developer can also check SIP invocations from HTTP servlets and so on.
In an operational system, the access log is used to analyze failures that occurred between the SIP and external SIP servers and the SIP client.

Settings for log output before shipping

Output file name logs/access.log
Maximum file size 3,000KB
Number of generations backed up 10000
Output format Date time, Route for reception, SIP method, SIP URI of From header, SIP URI of To header
Contents of output SIP message - info level

o For output format, see the settings for the access log of SIP servlet container (sipserver.xml).

Sample output 

 2004/12/11 00:01:44, SIPREQ, REGISTER, sip:68317@sip.oki.co.jp, sip:68317@sip.oki.co.jp
 2004/12/11 00:01:49, SIPRES, SUBSCRIBE, sip:68317@sip.oki.co.jp, sip:68317@sip.oki.co.jp
 2004/12/11 00:01:50, SIPREQ, NOTIFY, sip:68317@sip.oki.co.jp, sip:68317@sip.oki.co.jp
 2004/12/11 00:01:50, SIPREQ, SUBSCRIBE, sip:68317@sip.oki.co.jp, sip:68317@sip.oki.co.jp
 2004/12/11 00:01:50, SIPRES, NOTIFY, sip:68317@sip.oki.co.jp, sip:68317@sip.oki.co.jp
 2004/12/11 00:01:51, SIPREQ, SUBSCRIBE, sip:68317@sip.oki.co.jp, sip:67008@sip.oki.co.jp
 2004/12/11 00:01:51, SIPRES, NOTIFY, sip:67008@sip.oki.co.jp, sip:68317@sip.oki.co.jp

Console

The contents of the log can be output to the standard input of the console from which the server was started.
Before shipping, it is defined by SipConsole in the configuration file log4j.xml, specified such that the same contents as in the execution log is output.

In an operational system, it is recommended that output to the console is not performed.

System Log (syslog)

The monitoring of the logs can be integrated by specifying the output destination of the log (syslogd) as the system log (syslog). In the system log, the contents notified by SNMP trap are recorded.

For output to syslog, edit /etc/syslog.conf. When /etc/syslog.conf is edited, you must create a newly required log file, send a SIGHUP signal to syslogd, and then reload syslog.conf.

Example of editing /etc/syslog.conf 

 local6.info                          /var/log/newslog

Procedure to enable the edited syslog.conf 

 # touch /var/log/newslog
 # ps -ax | grep syslogd
  3609 ?        S      0:00 syslogd -m 0
 23962 pts/8    S      0:00 grep syslogd
 # kill -HUP 3609

Sample output 

 Dec 26 21:53:45 localhost [canary:0103002000111] SIP application "/sip-demo" stopped.
 Dec 26 21:53:46 localhost [system:0001002000039] SIP servlet engine terminated for fatal status!
 Dec 26 21:53:46 localhost last message repeated 1 time
 Dec 26 22:00:21 localhost [canary:0103001000101] SIP application "/sip-demo" installed.
 Dec 26 22:00:29 localhost [system:0001001000011] SIP servlet engine started.

If Linux is used as the OS, you must configure the settings such that the syslog daemon of Linux accepts the log from the network.
Edit /etc/init.d/syslog as in the following, execute /etc/init.d/syslog restart, and then restart the syslog daemon.

 case "$1" in
   start)
       echo -n "Starting system logger: "
       daemon syslogd -r

Log Configuration File

By editing log4j.xml at execution directory (or, in the case of WebLogic Portal (WLP), $BEA_HOME/weblogic81/common/lib/workshopLogCfg.xml or workshopLogCfgVerbose.xml), you can modify the log settings. log4j.xml consists of three types of components: categories, appenders, and layouts. For information on log4j.xml, see the Jakarta project Web page and so on.

There is a portion in the log configuration file where SNMP trap notification is described. You cannot edit this portion.

Categories

Based on categories, you can selectively enable or disable log requests, or record logs to multiple output destinations.

Category is a basic concept in the Log4J log defined by org.apache.log4j.Category class. Names can be specified for each category. The category names are case-sensitive and hierarchical names concatenated by periods (’.’) can be defined. (Example: category "com" is a parent category of "com.foo") There is a top category called the root category. The hierarchy of the category inherits attribute such as priority, witch is described below.

The log category names defined in SIP Servlet Engine include:

  • Application log: applog
  • SIP access log: msglog
  • Syslog: syslog

A priority is specified for each of the categories. By describing the priority in the log4J configuration file (log4j.xml), the output level of the log can be controlled. You can specify the log output level as fatal, error, warn, info, and debug, which are listed here in the order of priority.

Level Description
fatal Represents an error event of the server which possibly leads to shutdown of an application.
error Represents an error event with which application can still be in operation.
warn Represents a potentially hazardous situation.
info Represents an information message emphasizing the transition in the application in coarse granularity level.
debug Represents an information event of fine granularity level that is most useful in application debugging.

Note that the application log and SIP access log are to be output at info level regardless of the settings specified here.

Sample settings of log4j.xml 

 <category name="com.oki.sip">
     <priority value="info"/>
     <appender-ref ref="SipEngine"/>
     <appender-ref ref="SipConsole"/>
 </category>

This sample shows that, for a category having a prefix com.oki.sip, logs with output levels info and higher are recorded to the output destination (execution log and standard output) defined in SipEngine and SipConsole.

Appenders and Layouts

Defines the output destination and output format of the log.

In Log4j, multiple output destinations can be specified by using the concept of appender. For appenders, you can specify console, file, socket, Syslog daemon and so on.

Appender class Parameter Description of value
FileAppender Class to append a log event to a file
File Destination file name (directories can be included)
Append Whether to open a file in append mode. (true/false)
RollingFileAppender FileAppender class which is extended so as to backup a log file when it reaches a certain size
File Destination file name (directories can be included)
Append Whether to open a file in append mode. (true/false)
MaxBackupIndex Number of backups to be saved
MaxFileSize Maximum size of a log file
SyslogAppender
(.log4j.net.)		 Class that sends a log message to local or remote syslog daemon
SyslogHost Name of the host where the syslog daemon of the output destination is operated (Local: localhost)
Facility The facility name of the named syslog, which is one of the following:
KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7.
In this system, one from LOCAL0 to LOCAL6 is specified.
NullAppender
(.log4j.performance.)		 > A dummy appender. Class for specifying not to output a log.

By specifying a layout to the attribute of the appender, the output format can be controlled for each of the appenders.

Layout class Parameter Description of value
PatternLayout Class for flexible layout using a pattern string
ConversionPattern Sets a pattern string

Using PatternLayout class allows specification of an output format by conversion pattern similar to the print function in C language. The following shows the conversion characters that can be specified by pattern string. The conversion characters are the characters subsequent to percent symbol (’%’) which can be combined with options or conversion modifiers.

Conversion character Description
c Log category
Number of category hierarchies to be output can be specified
Example: If category is a.b.c and %c{1} is specified, then the output result is c
C Name of the class for log output
Number of class hierarchies to be output can be specified
Example: If class is x.y.z and %C{1} is specified, then the output result is z
Warning: Since the generation of class information is slow, this should only be applied when execution speed is not a problem.
d Date and time of log output
Date format is specified/Initial value: ISO8601 format
Example of date format specification: If %d{HH:mm:ss,ddd} is specified, the result is 18:37:59,11
F Name of the file for log output
Warning: Since the generation of class information is slow, this should only be applied when execution speed is not a problem.
m String set in a log event (log message)
n Linefeed character that depends on platform
p Log output level (Priority)
t Name of the thread that generated the log

Sample settings of log4j.xml 

 <appender name="SipEngine" class="org.apache.log4j.RollingFileAppender">
   <param name="File" value="logs/sip-engine.log" />
   <param name="Append" value="true" />
   <param name="MaxFileSize" value="3000KB" />
   <param name="MaxBackupIndex" value="10000" />
   <layout class="org.apache.log4j.PatternLayout">
     <param name="ConversionPattern" value="%d %-5p %-15c{1} [%t]\t: %m%n"/>
   </layout>
 </appender>

This example shows the definition of an execution log. An appender that uses RollingFileAppender is defined with the name SipEngine, the log is recorded in the output log logs/sip-engine.log, and when the file size exceeds 3000KB, it is backed up as a file having the name logs/sip-engine.log.n When the number of backup files exceeds 10000, the files are deleted in chronological order (i.e., rotate setting). The output format of this log is specified as %d %-5p %-15c{1} [%t]\t: %m%n (Date and time){ISO8601} Output level Category [Thread name]{Tab}: Output message {Linefeed}).

Last Modified:Fri Jan 07 18:37:49 JST 2005

 
Copyright © 2003, 2004 Oki Electric Industry Co.,Ltd. All rights reserved.