A server’s logging properties are defined in a Log Profile, which defines the logging subsystem used as well as other properties, such as output destinations, formats, and the level of severity required before a message is recorded. You can also configure different log profiles for the debug and production server versions.
EAServer supports industry-standard Java logging APIs, and provides APIs to log messages from components of other types. You can use the following logging subsystems:
The built-in EAS subsystem, which offers the same functionality available in EAServer 4.x versions, plus several enhancements including:
The ability to configure log levels so that messages below a specified level of severity are discarded.
Support for different logging configurations in the debug and production servers.
Optional archiving and compression of previous log file versions.
More control over message formatting.
Apache Log4j, which is commonly used on large projects. For more information on this package, see the Apache Log4j Documentation.
The Java Logging package, included in JDK 1.4. This API is the Sun proposed standard for logging in Java applications. For more information, see the Java Logging documentation. To use this package, your server must be running JDK 1.4 or later.
If you use Log4j or Java Logging, you can extend default behavior by plugging in your own code that implements the required interfaces. For example, you can install Log4j log handler classes that write messages to the Windows event log or to a database. Also, if you want one of these packages to log messages from your own component or application code, you can configure the server’s log profile so that server log messages go to the same destinations. In addition, if you use Log4j or the Java Logging system, you can log messages from in-server Java code by calling the logging API directly.
Using legacy logging methods
Regardless of the logging system you use, you can write messages
to the log using all of the methods supported in earlier versions
of EAServer, such as:
System.out.println or Jaguar.writeLog from Java code running in the server
ErrorLogging.log from PowerBuilder NVO components
JagLog from C or C++ components
IJagServer.writeLog from ActiveX components
Log output from these legacy methods can be configured using the srv_log logging category.
To change the log profile used in a server, display the Log/Trace tab in the Server Properties dialog box. To change the profiles using jagtool, set the following server properties:
com.sybase.jaguar.server.logging.profile.debug specifies the name of the log profile used in the debug server.
com.sybase.jaguar.server.logging.profile.prod specifies the name of the log profile used in the production server.
EAServer installs several predefined log profiles, as listed in Table 3-12.
You can configure log profiles in EAServer Manager or in a text editor.
Defining a new log profile
The easiest way to define a new log profile is to copy one of the existing definitions to a file, edit the file, then import the definition in Jaguar Manager as follows:
Copy the predefined log profile that is closest to the characteristics that you want, specifying a new file name with the .props extension.
Open the file in a text editor, and change the value of the com.sybase.jaguar.logprofile.name to match the base name. You can edit the remaining properties after importing the profile, using the Log Profile Configuration wizard.
Import the profile to EAServer Manager as follows:
Start EAServer Manager if it is not already running.
Highlight the Log Profiles folder in the left pane and choose File | Import.
Specify the file name you created and click OK.
You should see the new profile in the Log Profiles folder.
You can also create a log profile using the New Log Profile wizard.
Creating a log profile using the New Log Profile
wizard
In EAServer Manager, highlight the Log Profiles folder, and select File | New Log Profile Wizard.
The wizard guides you through the process of creating a log profile.
Configuring log
profiles
To configure log profiles, you can use either the Log Profile Configuration wizard or the Log Profile Properties page. The Log Profile Configuration wizard guides you through the basic steps required to configure a log profile for an EAS, Java Logging, or Log4j logging subsystem.
From within EAServer Manager, display the list of log profiles by expanding the Log Profiles folder.
Highlight the log profile you want to configure.
Select File | Configuration Wizard or File | Properties.
To find property descriptions for Log4j and Java Logging subsystems,
see:
To change the other properties, double-click the log profile name in the left pane to display the following:
Categories, which map to the various subsystems of EAServer. Different subsystems can use different category names for log messages, and you can configure the output for each category. Table 3-13 lists the category names used in EAServer. To change these properties:
Highlight Categories in the left pane to display the logging categories in the right pane.
Highlight the category name in the right pane and choose File | Configuration Wizard. Edit the properties described in “Category properties”.
You can also add new categories by highlighting Categories in the left pane and choosing File | New Log Category Wizard.
Handlers, which define how messages are logged. Associating a handler with a category determines how messages from that category are logged. To change these properties:
Highlight Handlers in the left pane to display the handler names in the right pane.
Highlight the handler name in the right pane and choose File | Configuration Wizard. Edit the properties described in “Handler properties”.
You can also add new handlers by highlighting Handlers in the left pane and choosing File | New Log Handler Wizard.
Formatters, which specify a format pattern for messages. To change these properties:
Highlight Formatters in the left pane to display the formatter names in the right pane.
Highlight the formatter name in the right pane and choose File | Configuration Wizard. Edit the properties described in “Formatter properties”.
You can also add new formatters by highlighting Formatters in the left pane and choosing File | New Log Formatter Wizard.
Exporting
log profiles
You can export log profile settings to a file. This is useful when you want to use the settings to control logging from Java client applications as described in “Using log profiles in Java client applications”. Export log profile settings as follows:
Highlight the Log Profile and Choose File | Export.
Specify the directory to export the file to, then choose Save. EAServer Manager creates profile.props in the specified directory, where profile is the name of the logging profile.
Category names map to the various subsystems of EAServer. Different subsystems can use different category names for log messages, and you can configure the output for each category. Table 3-13 lists the category names used in EAServer. Many of these are not used in the preconfigured log profiles, but you can add them.
Configuring
a log category using the Log Category Configuration wizard
The Log Category Configuration wizard guides you through the process of configuring a log category.
From within EAServer Manager, display the list of log profiles by expanding the Log Profiles folder.
Expand a log profile, then expand the Categories folder.
Highlight the log category you want to configure.
Select File | Configuration Wizard.
Table 3-14 describes the category settings.
Tab name / Setting name |
Specifies |
|---|---|
General / Description |
An optional description. |
Options / Level |
The logging level. Only messages of equal or greater severity are logged. Table 3-15 describes the severity codes. |
Options / Use Parent Handlers |
Whether to log to the parent category handlers as well as the handler associated with this category. |
Options / Parent |
The parent category. |
Options / Resource Bundle |
The name of a Java resource bundle containing localized messages that are logged from Java code. If this property is not set, the default resource bundle is the class ResourceBundle in the package with the same name as the category. For example, the default resource bundle for the category com.sybase.jaguar.server is com.sybase.jaguar.server.ResourceBundle. |
Handler |
One or more logging handler names. The handler properties specify how and where messages are logged. See “Handler properties” for more information. |
Table 3-15 lists the severity level codes. You can set the logging level in the category to discard messages below a specified severity level.
Handlers specify how and where messages are logged. You can associate handlers with categories to configure the output of messages from that category. Table 3-16 describes the handler settings.
Configuring
a log handler using the Log Handler Configuration wizard
The Log Handler Configuration wizard guides you through the process of configuring a log handler.
From within EAServer Manager, display the list of log profiles by expanding the Log Profiles folder.
Expand a log profile, then expand the Handlers folder.
Highlight the log handler you want to configure.
Select File | Configuration Wizard.
Tab name / Setting name |
Specifies |
|---|---|
General / Description |
An optional description. |
Type / Type |
The output type. Choose one of the following:
|
Type / File Name |
When logging to a file, the pattern string to name the output file. You can use the placeholders in Table 3-17. |
Type / Truncate Log File |
Whether to truncate the log file when the server starts. If truncation is not enabled, log messages from the server process are appended to those from the previous process. With truncation enabled, you can keep the previous log contents by enabling archiving (recommended) or rotation. |
Type / Max Size |
The maximum allowed size before archiving or rotating the log file. Use one of the following values:
|
Type / Max Time |
The maximum amount of time before archiving or rotating the log file; enter as HH:MM. |
Type / Rotate at Max |
Whether to rotate log files at start-up and when the maximum size or time is reached. If you enable rotation, the log file is renamed with a sequential numeric extension when a new file is started. For example, if the file is Jaguar.log, previous versions are named Jaguar.log.1, Jaguar.log.2, and so forth. |
Type / Archive Log Files |
Whether to archive log files at start-up and when the maximum size is reached. |
Type / Archive File Name |
If archiving is enabled, the pattern string to name the archived log files. You can use the placeholders in Table 3-17. |
Type / Compress Archive File |
If archiving is enabled, whether to compress the archived files. If you enable compression, the resulting archive name is the specified archive file name plus the “.zip” extension. |
Type / Console Type |
When writing to the console, the destination device. Choose stdout for standard output, and stderr for standard error. |
Type / Host Name |
When writing to a socket, the host name to connect the socket to. |
Type / Port |
When writing to a socket, the port number to connect the socket to. |
When specifying log file names and archive file names, you can use the placeholders in Table 3-17.
Formatters specify the format of logged messages. You can associate a formatter with a handler to specify the format of messages logged through the handler. Table 3-18 describes the formatter properties.
Configuring
a log formatter using the Log Formatter Configuration wizard
The Log Formatter Configuration wizard guides you through the process of configuring a log formatter.
From within EAServer Manager, display the list of log profiles by expanding the Log Profiles folder.
Expand a log profile, then expand the Formatter folder.
Highlight the log formatter you want to configure.
Select File | Configuration Wizard.
Tab name / Setting name |
Specifies |
|---|---|
General / Description |
An optional description. |
Type / Message Format |
The format pattern for the message text, using the placeholders listed in Table 3-19. You can use the Insert Tag control to insert these placeholders, or type them yourself. |
Type / Insert Tag |
When editing the message format, use this control to insert the placeholder tags. |
Type / Simple Date Format |
The format for timestamps in log messages. The pattern for the timestamps embedded in log messages, as converted to strings by java.text.SimpleDateFormat. For details, see the DateFormat API documentation. |
Table 3-19 lists the placeholders that you can use when specifying the message format pattern. Each placeholder represents part of the message.
Placeholder |
Represents |
|---|---|
|
The logging category name |
|
Message code (number) |
|
Message level (severity) |
|
Message text |
|
Processed message text, which consists of the message number (if specified when the message was logged) and the message text |
|
Sequence number |
|
Source file name |
|
Line number in the source file |
|
Method name in the source file |
|
Thread ID (enabled by setting server property com.sybase.jaguar.server.logspid) |
|
Exception thrown (if available) |
|
The timestamp, formatted as specified by the Simple Date Format setting |
|
A line break |
The EAServer Java client runtime classes also use the EAServer logging system. By default, the log level is ERROR and messages are sent to the console. You can change the client logging settings by specifying a configuration file. The same procedure works for Java/CORBA and EJB clients, as well as EAServer Manager and jagtool.
Specifying log settings for Java client applications
Use EAServer Manager to create a log profile with the desired settings and export the settings to a properties (.props) file.
When running the application, specify the logging properties to use by setting the Java system property com.sybase.jaguar.logger.config.file to the path and file name of the properties file. For example, to specify the system property on the command line, use syntax like this:
java -Dcom.sybase.jaguar.logger.config.file=mylog.props \ com.mycompany.MyClient
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|