Administering the Logging Service

In a Payara Server domain, log files have the following name and location by default:

For example, in a domain hosted on a given machine that includes a cluster with two managed servers (ClusterServer1 and ClusterServer1) and a standalone instance (StandaloneServer), the log files might be arranged in the following directory structure. In this directory structure, the server.log file for the DAS is located in domain-dir/logs.

You can change the default name or location of a log file by modifying the logging properties file for the corresponding instance, described in To Change the Name and Location of the Log File.

Payara Server writes log records in either the Oracle Diagnostics Logging (ODL) format or the Uniform Log Formatter (ULF) format. The default format is ODL. For information about changing the format, see Setting the Log File Format.

A custom formatter can also be used by specifying the fully qualified name of a class that extends the java.util.logging.Formatter class. The custom formatter class can be packaged in a JAR file and placed in the domain-dir/lib/ext directory, or implemented as a Hundred-Kilobyte Kernel (HK2) service and the JAR containing the formatter implementation placed in the as-install/modules directory.

Log records formatted in the ODL format are displayed as follows:

The following is an example of a log record formatted in the ODL format:

Log records formatted in the ULF format are displayed as follows:

The following is an example of a log record formatted in the ULF format:

The Administration Console presents log records in a more readable display. For information about viewing log records using the Administration Console, see Viewing Log Records.

By default, when a log file grows to 2 MB, Payara Server renames (rotates) the file to incorporate a timestamp and creates a new log file. The log file is renamed as server.log date, where date is the date and time that the file was rotated.

You can configure the logging service to change the default settings for log file rotation, as explained in Setting Log File Rotation.

To change the name and location of the log file, first use the list-log-attributes subcommand to obtain the current log attribute setting for the log file name and location.

Then use the set-log-attributes subcommand to specify the new name or location. The default target for these two subcommands is the DAS. However, you can optionally specify one of the following targets:

This example changes the name of the cluster log file for Cluster1 to cluster1.log. Cluster1 has two server instances: ClusterServer1 and ClusterServer2.

You can view the full syntax and options of these subcommands by typing asadmin help list-log-levels and asadmin help set-log-attributes at the command line.

You can set the name and location of the logging properties file by setting the java.util.logging.config.file system property. By setting this system property, you can have a single logging properties file that is used by all instances running on the same host.

The following example changes the location of the logging properties file to /space/mylogging/logging.properties:

Payara Server provides the means to list all loggers and their log levels. Listing the loggers provides a convenient means to view current loggers and log levels either prior to or after making log level changes.

Use the list-log-levels subcommand in remote mode to list the modules and their current log levels. The default target for this subcommand is the DAS. However, you can optionally specify one of the following targets:

This example shows a partial list of the existing loggers and their log levels in the DAS.

This example shows a partial list of the loggers and log levels for the instance MyServer2.

You can view the full syntax and options of the subcommand by typing asadmin help list-log-levels at the command line.

The global log level specifies the events that are logged across all loggers. The default level for messages output to the console is INFO (which also includes EMERGENCY, ALERT, SEVERE, and WARNING messages).

Use the set-log-levels subcommand in remote mode to set the global log level. The default target for this subcommand is the DAS. However, you can optionally specify one of the following targets using the --target option:

By setting the log level of the ConsoleHandler, you set the global log level for all loggers. This example sets the global log level in the DAS to INFO:

You can view the full syntax and options of the subcommand by typing asadmin help set-log-levels at the command line.

A module log level specifies the events that are logged for a particular logger. The default level for messages output to the console is INFO (which also includes EMERGENCY, ALERT, SEVERE, and WARNING messages). The global log level is overridden by a module-specific log level.

By default, the module log level is set to FINE. The lines for the loggers in the logging properties file might look like this:

Because setting log levels is a dynamic operation, you do not need to restart Payara Server for changes to take effect.

This example sets the log level for the web container logger to WARNING on the target instance ManagedServer1:

The following example sets the log level for security and web container loggers in the DAS.

You can view the full syntax and options of the subcommand by typing asadmin help set-log-levels at the command line.

Use the set-log-file-format subcommand in remote mode to set the formatter used by Payara Server to format log records in log files. You can also use the set-log-attributes subcommand.

Log formats for all server instances in a cluster will be the same. For information about log formats, see Log Records.

This example sets the log file format to ULF for standalone instance ManagedServer1 using the set-log-file-format subcommand.

This example sets the log file format to ULF for standalone instance ManagedServer1 using the set-log-attributes subcommand.

You can view the full syntax and options of the set-log-file-format subcommand by typing asadmin help set-log-file-format at the command line. You can view the full syntax and options of the set-log-attributes subcommand by typing asadmin help set-log-attributes at the command line.

Payara Server supports the use of ANSI coloured log entries when running in verbose mode under the uniform log format (ULF).

To enable ANSI colours run the following command using the Asadmin CLI:

Besides the standard Uniform Log Format (ULF) and Oracle Diagnostics Logging (ODL) formats Payara Server provides a JSON format. With this format, every entry is formatted as a JSON object string. These entries can be easily processed by any JSON parser for further data processing.

Once the JSON formatter is enabled, the server’s log file may look similar to this sample:

Use the set-log-attributes subcommand in remote mode to exclude specific name-value fields from log records. If the excludeFields attribute is not specified, all name-value fields are included.

The following fields can be excluded:

Follow these instructions:

Use the set-log-attributes command in remote mode to set multiline mode. When multiline mode is enabled (the default), the body of a log message starts on a new line after the message header and is indented.

Multiline mode is enabled by default. The following example disables multiline mode in log files for standalone instance ManagedServer1:

You can view the full syntax and options of the subcommand by typing asadmin help set-log-attributes at the command line.

Use the set-log-attributes subcommand in remote mode to change the log rotation file size. The default target of this subcommand is the DAS.

Optionally, you can target a configuration, server, instance, or cluster. The minimum size that can be set is 500 KB.

The following example sets the log file rotation size to 1 MB for the standalone instance ManagedServer1:

You can view the full syntax and options of the subcommand by typing asadmin help set-log-attributes at the command line.

Use the set-log-attributes subcommand in remote mode to change the log file rotation time limit interval. The default target of this subcommand is the DAS. Optionally, you can target a configuration, server, instance, or cluster. The default value is 0.

The following example sets the log file rotation time limit for the cluster Cluster1, which has the instances ClusterServer1 and ClusterServer2.

You can view the full syntax and options of the subcommand by typing asadmin help set-log-attributes at the command line.

Use the set-log-attributes subcommand in remote mode to change the limit on the number of log files that the server creates to store old log messages. The default target of this subcommand is the DAS.Optionally, you can target a configuration, server, instance, or cluster. The default limit value is 0, which results in no limit placed on the number of rotated log files that are retained.

The behavior of the com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles attribute is as follows:

The following example sets the log limit number of retained log files for the DAS to 10.

You can view the full syntax and options of the subcommand by typing asadmin help set-log-attributes at the command line.

Payara Server can be configured to automatically compress rotated log files in an automatic manner to save disk space.

You can rotate log files manually by using the rotate-log subcommand in remote mode. The default target of this subcommand is the DAS. Optionally, you can target a configuration, server, instance, or cluster. When you use this subcommand, the target log file is immediately moved to a new time-stamped file and a new log file is created.

Because log rotation is a dynamic operation, you do not need to restart Payara Server for changes to take effect.

The following example rotates the server.log file for ManagedServer2 to server.log_`yyyy-mm-dd`T`hh-mm-ss, where yyyy-mm-dd`T`hh-mm-ss represents the time when the file is rotated, and creates a new server.log file in the default location.

You can view the full syntax and options of the subcommand by typing asadmin help rotate-log at the command line.

A comma-separated list of log handlers is installed during startup of the Java Virtual Machine (JVM) host. The default log handler that is provided in the logging.properties file, ConsoleHandler, is configured as follows:

In Payara Server, the best approach to developing a custom handler is to define a Hundred-Kilobyte Kernel (HK2) component that implements the handler contract. Payara Server registers this handler automatically because it is an HK2 component. There is no task required of the administrator.

To configure a custom handler that is not developed as an HK2 component, add the new handler to the logging.properties file after the developer has put the custom handler JAR file into the domain-dir/lib/ext directory.

Before You Begin

If you set a handler by setting the handlers attribute in the logging properties file, the class that extends java.util.logging.Handler must be in the server classpath.

This example adds the custom logger com.example.logging.MyHandler to the logging properties file of the DAS.

You can view the full syntax and options of the subcommand by typing asadmin help set-log-attributes at the command line.

To configure the Log to File option using theAdmin Console:

Use the following command to enable or disable the logging to a file feature:

To configure the Log to Console option using the Admin Console:

Use the following command to enable or disable the log to console feature:

To configure the Fast Logging option, set it in the Logger settings.

Use the following command to enable or disable fast logging:

This example shows collecting the log files for the cluster MyCluster and compiling them into a ZIP archive in the /space/output directory.

When the ZIP file created by the preceding command is uncompressed, the following directory structure is created:

You can view the full syntax and options of the subcommand by typing asadmin help collect-log-files at the command line.

This example lists the logger name, subsystem, and description for each logger. Some lines of output are omitted from this example for readability.

You can also view the full syntax and options of the subcommand by typing asadmin help list-loggers at the command line.

The Log to File option will provide a way to enable and disable logging to a file of Payara Server Notifications. When disabled this should help to minimize disk usage. This option will be more accommodating if Payara Server is running in cloud environment where disk space is scarce.

The Rotation On Date Change option provides a way to set the log rotation when the system date changes (at midnight, by default).

The File Rotation Limit option provides a way to change the file size at which the server triggers the log file rotation. This option accepts an integer value specifying the maximum size of the log file, after which a file rotation will occur.

The minimum size it can be set to is 500KB (500.000 bytes).

The File Rotation Time Limit option provides a way to trigger the notification log file rotation based on a fixed time limit. The value of this setting is an integer that defines the time limit in minutes until the log rotation gets triggered.

The Log File Logging Format option can be used to change the notification log entries' format. There are 3 logging formats available: ULF, ODL and JSON, each one represented by a specific formatter class present in the Payara Platform API.

The Maximum History Files option provides a way to set the limit on the number of notification log files that can be created by Payara Server.

Once the number of files reaches the set limit, the oldest rotated log file is deleted. If the value for this option is set 0, all the rotated log files are preserved.

The Log File option provides a way to change the default name and location of the notification log files.

The Compress on Rotation option provides a way to enable the automatic compression of notification log files on rotation.