type=page
status=published
title=Administering the Logging Service
next=monitoring.html
prev=webapps.html
~~~~~~

= Administering the Logging Service

[[GSADG00010]][[abluj]]


[[administering-the-logging-service]]
== 7 Administering the Logging Service

This chapter provides instructions on how to configure logging and how
to view log information in the {productName} 7 environment.

The following topics are addressed here:

* link:#abluk[About Logging]
* link:#gklmn[Configuring the Logging Service]
* link:#gkobx[Viewing Log Records]
* link:#CEGGHGIJ[Listing Loggers]

Instructions for accomplishing these tasks and editing logging service
properties in the Administration Console are available from the
Administration Console online help.

[[abluk]][[GSADG00554]][[about-logging]]

=== About Logging

Logging is the process by which {productName}
captures information about events that occur, such as configuration
errors, security failures, or server malfunction. This data is recorded
in log files and is usually the first source of information when
problems occur. Analyzing the log files can help you to follow events
that occur in the server runtime and determine the overall health of the
server.

Although application components can use the Apache Commons Logging
Library to record messages, the platform standard JSR 47 Logging API is
recommended for better log configuration. For more information about JSR 47,
see `http://jcp.org/en/jsr/detail?id=47`.

The following topics are addressed here:

* link:#ablul[Log Files]
* link:#gkres[Logger Namespaces]
* link:#gkjft[Logging Targets]
* link:#gkkit[Logging Properties]

[[ablul]][[GSADG00719]][[log-files]]

==== Log Files

{productName} log records are captured in the
server log file, which captures information about the operation of a server instance
running in the domain. Each instance, managed server
instance (that is, each cluster member), and the domain administration
server (DAS) has an individual server log file.

The following topics are addressed here:

* link:#gkmep[Log File Names and Locations]
* link:#gkmex[Log Records]
* link:#gkmdz[Log Rotation]

[[gkmep]][[GSADG00644]][[log-file-names-and-locations]]

===== Log File Names and Locations

In an {productName} domain, log files have the
following name and location by default:

[width="100%",cols="27%,73%",options="header",]
|===
|Instance |Default Log File Name and Location
|DAS |domain-dir``/logs/server.log``
|Each server instance |instance-dir``/logs/server.log``
|Cluster instance |instance-dir``/logs/server.log``
|===


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``.

[source]
----
as-install-parent directory
  glassfish/
    domains/
      domain-dir/
        logs/
          server.log
    nodes/
      hostname/
        ClusterServer1/
          logs/
            server.log
        ClusterServer2/
          logs/
            server.log
        StandaloneServer/
          logs/
            server.log
----

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

[[gkmex]][[GSADG00645]][[log-records]]

===== Log Records

{productName} 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 link:#CEGDJEBG[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:

[source]
----
[yyyy-mm-ddThh:mm:ss.SSS-Z][ProductName-Version][Log Level]
[Message ID][LoggerName][Key Value Pairs][[Message]]
----

* `[` and `]` mark the beginning and end of fields in the record. Some
fields may be empty.
* yyyy-mm-dd`T`hh:mm:ss.SSSS-Z represents the date and time that the
record was created. For example: `2013-04-12T08:08:30.154-0700`
* ProductName-Version represents the current version of {productName}. For example: `glassfish`
* Log Level represents the log level. You can set any of the following
values: `EMERGENCY`, `ALERT`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`,
`FINE`, `FINER`, and `FINEST`. The default is `INFO`.
* Message ID consists of a module code that indicates the origin of the
message and the message number. For example: `AS-WEB-GLUE-00172`
* LoggerName represents a hierarchical logger namespace that identifies
the source of the log module. For example: `jakarta.enterprise.web`
* Key Value Pairs represents pairs of key names and values. For example:
`timeMillis: 1365779310154`
* Message represents the text of the log message. For multiline
messages, `[[` marks the end of the first line, and `]]` marks the end
of the message. Multiline messages start on a new line after the message
header and are indented.

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

[source]
----
[2021-04-12T08:08:30.154-0700] [glassfish 7.0] [INFO] [AS-WEB-GLUE-00172] [jakarta.enterprise.web] [tid: _ThreadID=217 _ThreadName=admin-listener(21)]
[timeMillis: 1365779310154] [levelValue: 800] [[
  Loading application [payroll] at [/payroll]]]
----

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

[source]
----
[#|yyyy-mm-ddThh:mm:ss.SSS-Z|Log Level|ProductName-Version|LoggerName|Key Value Pairs|Message|#]
----

* `[#` and `#]` mark the beginning and end of the record.
* The vertical bar (`|`) separates the fields of the record.
* yyyy-mm-dd`T`hh:mm:ss.SSSS-Z represents the date and time that the
record was created. For example: `2013-04-18T09:27:44.315-0700`
* Log Level represents the log level. You can set any of the following
values: `EMERGENCY`, `ALERT`, `SEVERE`, `WARNING`, `INFO`, `CONFIG`,
`FINE`, `FINER`, and `FINEST`. The default is `INFO`.
* ProductName-Version represents the current version of {productName}. For example: `glassfish`
* LoggerName represents a hierarchical logger namespace that identifies
the source of the log module. For example: `jakarta.enterprise.web.core`
* Key Value Pairs represents pairs of key names and values and can
include a message ID. For example: `_MessageID=AS-WEB-CORE-00306`.
+
Message IDs are included for all {productName}
`EMERGENCY`, `ALERT`, `SEVERE`, and `WARNING` messages, and for many
`INFO` messages.
* Message represents the text of the log message. Multiline messages
start on a new line after the message header and are indented.

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

[source]
----
[#|2013-04-18T09:27:44.315-0700|INFO|glassfish 7.0|jakarta.enterprise.web.core|
_ThreadID=15;_ThreadName=RunLevelControllerThread-1366302462682;_TimeMillis=1366302464315;_LevelValue=800;_MessageID=AS-WEB-CORE-00306;|
  Setting JAAS app name glassfish-web|#]
----

The Administration Console presents log records in a more readable
display. For information about viewing log records using the
Administration Console, see link:#gkobx[Viewing Log Records].

[[gkmdz]][[GSADG00646]][[log-rotation]]

===== Log Rotation

By default, when a log file grows to 2 MB, {productName} 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 link:#gklni[Setting Log File
Rotation].

[[gkres]][[GSADG00720]][[logger-namespaces]]

==== Logger Namespaces

{productName} provides a logger for each of its
modules. The following list is an example of the logger namespaces in a
server instance as they appear when using the `list-log-levels`
subcommand.

[source]
----
java.util.logging.ConsoleHandler     <FINEST>
jakarta.enterprise.resource.corba     <INFO>
jakarta.enterprise.resource.javamail  <INFO>
jakarta.enterprise.resource.jdo       <INFO>
jakarta.enterprise.resource.jms       <INFO>
jakarta.enterprise.resource.jta       <INFO>
jakarta.enterprise.resource.resourceadapter     <INFO>
jakarta.enterprise.resource.sqltrace  <INFO>
jakarta.enterprise.resource.webcontainer.jsf.application  <INFO>
jakarta.enterprise.resource.webcontainer.jsf.config       <INFO>
jakarta.enterprise.resource.webcontainer.jsf.context      <INFO>
jakarta.enterprise.resource.webcontainer.jsf.facelets     <INFO>
jakarta.enterprise.resource.webcontainer.jsf.lifecycle    <INFO>
jakarta.enterprise.resource.webcontainer.jsf.managedbean  <INFO>
jakarta.enterprise.resource.webcontainer.jsf.renderkit    <INFO>
jakarta.enterprise.resource.webcontainer.jsf.resource     <INFO>
jakarta.enterprise.resource.webcontainer.jsf.taglib       <INFO>
jakarta.enterprise.resource.webcontainer.jsf.timing       <INFO>
jakarta.enterprise.system.container.cmp         <INFO>
jakarta.enterprise.system.container.ejb         <INFO>
jakarta.enterprise.system.container.ejb.mdb     <INFO>
jakarta.enterprise.system.container.web         <INFO>
jakarta.enterprise.system.core.classloading     <INFO>
jakarta.enterprise.system.core.config   <INFO>
jakarta.enterprise.system.core.naming   <INFO>
jakarta.enterprise.system.core.security <INFO>
jakarta.enterprise.system.core.selfmanagement   <INFO>
jakarta.enterprise.system.core.transaction      <INFO>
jakarta.enterprise.system     <INFO>
jakarta.enterprise.system.tools.admin   <INFO>
jakarta.enterprise.system.tools.backup  <INFO>
jakarta.enterprise.system.tools.deployment      <INFO>
jakarta.enterprise.system.util          <INFO>
jakarta.enterprise.system.webservices.registry  <INFO>
jakarta.enterprise.system.webservices.rpc       <INFO>
jakarta.enterprise.system.webservices.saaj      <INFO>
javax     <INFO>
org.apache.catalina    <INFO>
org.apache.coyote      <INFO>
org.glassfish.wasp      <INFO>
org.jvnet.hk2.osgiadapter   <INFO>
----

For information about how to display logger namespaces and log levels,
see link:#gjirr[To List Log Levels]. For information about how to
display a list of loggers and logger details, see link:#CEGGICGF[To List
Loggers].

[[gkjft]][[GSADG00721]][[logging-targets]]

==== Logging Targets

Each instance in an {productName} domain has a
dedicated log file, and each instance and cluster has its own logging
properties file. To configure logging for an instance or a cluster,
{productName} allows you target specific log
files or logging properties files when you do the following:

* Set global or module-specific log levels
* Rotate log files or compress them into a ZIP archive
* Change logging property attributes
* List log levels or log attributes

The following subcommands optionally accept a target specification. A
target can be a configuration name, server name, cluster name, or
instance name, and is specified as either an operand or as a value
passed using the `--target` option. If no target is specified when using
any of these subcommands, the default target is the DAS.

[width="100%",cols="27%,47%,26%",options="header",]
|===
|Subcommand |Description |Target Specification
|link:reference-manual/collect-log-files.html#GSRFM00007[`collect-log-files`] |Collects all available log files
into a ZIP archive. |`--target``=`target-name

|link:reference-manual/list-log-attributes.html#GSRFM00182[`list-log-attributes`] |Lists logging attributes in
the logging properties file. |target-name operand

|link:reference-manual/list-log-levels.html#GSRFM00183[`list-log-levels`] |Lists the loggers in the logging
properties file and their log levels. |target-name operand

|link:reference-manual/rotate-log.html#GSRFM00224[`rotate-log`] |Rotates the log file by renaming it and
creating a new log file to store new messages. |`--target``=`target-name

|link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] |Sets the specified logging
attributes in the logging properties file. |`--target``=`target-name

|link:reference-manual/set-log-file-format.html#GSRFM879[`set-log-file-format`] |Sets the log file formatter.
|`--target``=`target-name

|link:reference-manual/set-log-levels.html#GSRFM00228[`set-log-levels`] |Sets the log level for one or more
loggers listed in the logging properties file. |`--target``=`target-name
|===


[[gkkit]][[GSADG00722]][[logging-properties]]

==== Logging Properties

The DAS as well as each configuration, instance, and cluster has its own
set of logging properties that are maintained in individual
configuration files. A logging properties file is named
`logging.properies` and includes the following information:

* Log file name and location
* Logger names and levels
* Properties for custom handlers
* Log rotation and logger format properties

By default in an {productName} domain, logging
properties files are created in the following locations:

[width="100%",cols="18%,82%",options="header",]
|===
|Target |Default Location of Logging Properties File
|DAS |domain-dir``/config```/logging.properties`

|A configuration |domain-dir`/config/`config-name`/logging.properties`,
where config-name represents the name of a configuration that is shared
by one or more instances or clusters.

|An instance
|domain-dir``/config```/`instance-name`-config/logging.properties`, where
instance-name represents the name of the instance.

|A cluster
|domain-dir`/config/`cluster-name`-config/logging.properties`, where
cluster-name represents the name of the cluster.
|===


For information about configuring logging properties, see
link:#gklmn[Configuring the Logging Service].

[[gklmn]][[GSADG00555]][[configuring-the-logging-service]]

=== Configuring the Logging Service

This section contains the following topics:

* link:#gklmx[Changing the Name and Location of Logging Service Files]
* link:#gklml[Setting Log Levels]
* link:#CEGDJEBG[Setting the Log File Format]
* link:#gklni[Setting Log File Rotation]
* link:#gklnk[Adding a Custom Logging Handler]

[[gklmx]][[GSADG00723]][[changing-the-name-and-location-of-logging-service-files]]

==== Changing the Name and Location of Logging Service Files

This section explains how to change the name and location of the
following logging service files:

* Log file
* Logging properties file

[[gkmak]][[GSADG00375]][[to-change-the-name-and-location-of-the-log-file]]

===== To Change the Name and Location of the Log File

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:

* Configuration name — to target all instances or clusters that share a specific configuration name.
* Server name — to target only a specific server.
* Instance name — to target only a specific instance.
* Cluster name — to target only a specific cluster.

1. Ensure that the target server or cluster is running.
Remote subcommands require a running server.

2. Use the link:reference-manual/list-log-attributes.html#GSRFM00182[`list-log-attributes`]
subcommand in remote mode to obtain the current log attribute settings.
The name and location of the log file is set with the
`com.sun.enterprise.server.logging.GFFileHandler.file` attribute of the
logging properties file.
Optionally you can target a configuration, server, instance, or cluster.
If you do not specify a target, the log attribute settings for the DAS are displayed.

3. Use the link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`]
subcommand in remote mode to define a custom name or location of the log file.
If you do not specify a target, the log file for the DAS is targeted by default.
If you target a cluster, the name of the cluster log file for
each member instance can be changed (the server log file name cannot).

[[GSADG00174]][[gkmal]]
Example 7-1 Changing the Name and Location of a Cluster's Log File

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

[source]
----
asadmin> list-log-attributes Cluster1
com.sun.enterprise.server.logging.GFFileHandler.alarms <false>
com.sun.enterprise.server.logging.GFFileHandler.file
<${com.sun.aas.instanceRoot}/logs/server.log>
com.sun.enterprise.server.logging.GFFileHandler.flushFrequency  <1>
.
.
.
log4j.logger.org.hibernate.validator.util.Version <warn>
Command list-log-attributes executed successfully.
asadmin> set-log-attributes --target Cluster1
com.sun.enterprise.server.logging.GFFileHandler.file=
${com.sun.aas.instanceRoot}/logs/cluster1.log
com.sun.enterprise.server.logging.GFFileHandler.file
logging attribute set with value ${com.sun.aas.instanceRoot}/logs/cluster1.log
These logging attributes are set for Cluster1.
ClusterServer1 :
com.sun.enterprise.server.logging.GFFileHandler.file
logging attribute set with value ${com.sun.aas.instanceRoot}/logs/cluster1.log
These logging attributes are set for Cluster1.

ClusterServer2 :
com.sun.enterprise.server.logging.GFFileHandler.file
logging attribute set with value ${com.sun.aas.instanceRoot}/logs/cluster1.log
These logging attributes are set for Cluster1.

Command set-log-attributes executed successfully.
----

[[GSADG864]]

See Also

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.

[[gkmcz]][[GSADG00376]][[to-change-the-name-and-location-of-the-logging-properties-file]]

===== To Change the Name and Location of the Logging Properties File

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.

[NOTE]
====
Setting the `java.util.logging.config.file` system property causes all
other {productName} logging properties files on
the host to be overridden.
====


1. Set the `java.util.logging.config.file` system property.
For example, you can use the following `java` command:
+
[source]
----
java -Djava.util.logging.config.file=properties_file
----
Alternatively, you can use the Administration Console to set this system property.

2. To apply your change, restart {productName}.

[[GSADG00175]][[gkmgz]]
Example 7-2 Setting the `java.util.logging.config.file` System Property

The following example changes the location of the logging properties
file to `/space/mylogging/logging.properties`:
[source]
----
java -Djava.util.logging.config.file=/space/mylogging/logging.properties
----

[[gklml]][[GSADG00724]][[setting-log-levels]]

==== Setting Log Levels

The log level determines the granularity of the message that is logged,
from error only (`EMERGENCY`) to detailed debug (`FINEST`). The
following values apply: `EMERGENCY`, `ALERT`, `SEVERE`, `WARNING`,
`INFO`, `CONFIG`, `FINE`, `FINER`, and `FINEST`. These log levels are
hierarchically inclusive, which means that if you set a particular log
level, such as INFO, the messages that have log levels above that level
(`EMERGENCY`, `ALERT`, `SEVERE`, and `WARNING`,) are also included. If
you set the log level to the lowest level, `FINEST`, your output
includes all the messages in the file. The default setting is `INFO`.

You can list current log levels of all loggers specified in the
`logging properties` file. In some cases, loggers that have not been
created by the respective containers will also appear in the list.

You can set log levels that are global or logger-specific. When you set
a global log level, the log level goes into effect for all loggers. If
you set the log level for a specific logger that is different from the
global log level, the logger-specific setting takes precedence. In
addition, when setting log levels, you can target a configuration,
server, instance, or cluster.

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

Setting either global or logger-specific log levels is done by using the
`set-log-levels` subcommand. Listing log levels is done by using the
`list-log-levels` subcommand.

The following topics are addressed here:

* link:#gjirr[To List Log Levels]
* link:#ghmep[To Set the Global Log Level]
* link:#ghmdu[To Set Module Log Levels]

[[gjirr]][[GSADG00377]][[to-list-log-levels]]

===== To List Log Levels

{productName} 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:

* Configuration name — to target all instances or clusters that share a specific configuration name.
* Server name — to target a specific server.
* Instance name — to target a specific instance.
* Cluster name — to target a specific cluster.

1. Ensure that the DAS is running. Remote subcommands require a running server.
2. List the existing module loggers and log levels by using the
link:reference-manual/list-log-levels.html#GSRFM00183[`list-log-levels`] subcommand.

[[GSADG00176]][[gjiti]]
Example 7-3 Listing Logger Levels for Modules

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

[source]
----
asadmin> list-log-levels
jakarta.enterprise.system.container.cmp <INFO>
jakarta.enterprise.system.tools.admin <INFO>
java.util.logging.ConsoleHandler <FINEST>
jakarta.enterprise.system.container.web <INFO>
jakarta.enterprise.system.util <INFO>
jakarta.enterprise.resource.webcontainer.jsf.timing <INFO>
javax <INFO>
jakarta.enterprise.resource.corba <INFO>
...
Command list-log-levels executed successfully.
----

[[GSADG00177]][[gkkot]]
Example 7-4 Listing Log Levels for an Instance

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

[source]
----
asadmin> list-log-levels MyServer2
java.util.logging.ConsoleHandler <FINEST>
jakarta.enterprise.resource.corba  <INFO>
jakarta.enterprise.resource.javamail   <INFO>
jakarta.enterprise.resource.jdo <INFO>
jakarta.enterprise.resource.jms <INFO>
jakarta.enterprise.resource.jta <INFO>
jakarta.enterprise.resource.resourceadapter <INFO>
jakarta.enterprise.resource.sqltrace <FINE>
...
Command list-log-levels executed successfully.
----

[[GSADG865]]

See Also

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

[[ghmep]][[GSADG00378]][[to-set-the-global-log-level]]

===== To Set the Global Log Level

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:

* Configuration name — to target all instances or clusters that share a specific configuration name.
* Server name — to target a specific server.
* Instance name — to target a specific instance.
* Cluster name — to target a specific cluster.

1. Ensure that the target server or cluster is running.
2. Set the global log level by using the
link:reference-manual/set-log-levels.html#GSRFM00228[`set-log-levels`] subcommand, specifying the log level
of the `java.util.logging.ConsoleHandler` logger.
The `ConsoleHandler` has a separate log level setting that limits the
messages that are displayed. For example:
+
[source]
----
java.util.logging.ConsoleHandler <FINEST>
----

[[GSADG00178]][[ghmfi]]
Example 7-5 Changing the Global Log Level for All Module Loggers

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`:

[source]
----
asadmin> set-log-levels java.util.logging.ConsoleHandler=INFO
java.util.logging.ConsoleHandler package set with log level INFO.
These logging levels are set for server.

Command set-log-levels executed successfully.
----

[[GSADG866]]

See Also

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

[[ghmdu]][[GSADG00379]][[to-set-module-log-levels]]

===== To Set Module Log Levels

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 (the modules
are indicated in bold):

[source]
----
jakarta.enterprise.system.tools.level=FINE
jakarta.enterprise.system.container.ejb.level=FINE
jakarta.enterprise.system.core.security.level=FINE
jakarta.enterprise.system.tools.admin.level=FINE
jakarta.enterprise.level=FINE
jakarta.enterprise.system.container.web.level=FINE
----

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

1. Ensure that the target server or cluster is running. Remote subcommands require a running server.

2. List the existing module loggers and their log levels by using the
link:reference-manual/list-log-levels.html#GSRFM00183[`list-log-levels`] subcommand.

3. Set the log level for a module by using the
link:reference-manual/set-log-levels.html#GSRFM00228[`set-log-levels`] subcommand.
Your choices are `EMERGENCY`, `ALERT`, `SEVERE`, `WARNING`, `INFO`,
`CONFIG`, `FINE`, `FINER`, and `FINEST`.

[[GSADG00179]][[ghmev]]
Example 7-6 Setting the Log Level for a Module Logger

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

[source]
----
asadmin> set-log-levels --target ManagedServer1
jakarta.enterprise.system.container.web=WARNING
jakarta.enterprise.system.container.web package set with log level WARNING.
These logging levels are set for ManagedServer1.
ManagedServer1 :
jakarta.enterprise.system.container.web package set with log level WARNING.
These logging levels are set for ManagedServer1.

Command set-log-levels executed successfully.
----

[[GSADG00180]][[gjkat]]
Example 7-7 Setting Log Levels for Multiple Loggers

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

[source]
----
asadmin> set-log-levels jakarta.enterprise.system.core.security=FINE:
jakarta.enterprise.system.container.web=WARNING
jakarta.enterprise.system.container.web package set with log level WARNING.
jakarta.enterprise.system.core.security package set with log level FINE.
These logging levels are set for server.

Command set-log-levels executed successfully.
----

[[GSADG867]]

See Also

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

[[CEGDJEBG]][[GSADG1062]][[setting-the-log-file-format]]

==== Setting the Log File Format

You can set the format for log records in log files. The following
topics are addressed here:

* link:#CEGFFJDG[To Set the Log File Format]
* link:#CEGGBJCC[To Exclude Fields in Log Records]
* link:#CEGBBEAH[To Set Multiline Mode]

[[CEGFFJDG]][[GSADG1063]][[to-set-the-log-file-format]]

===== To Set the Log File Format

Use the `set-log-file-format` subcommand in remote mode to set the
formatter used by {productName} 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 link:#gkmex[Log
Records].


[NOTE]
====
Changing the log format forces log rotation to avoid mixed format in the
same file.
====


1. Ensure that the target server or cluster is running. Remote commands require a running server.
2. Set the formatter by using the
link:reference-manual/redeploy.html#GSRFM00217[`set-log-file-format`] subcommand.
3. To apply your change, restart {productName}.

[[GSADG1064]][[sthref23]]
Example 7-8 Setting the Log File Format using `set-log-file-format`

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

[source]
----
asadmin> set-log-file-format --target ManagedServer1 ulf
The log file formatter is set to com.sun.enterprise.server.logging.UniformLogFormatter for instance ManagedServer1.
Command set-log-file-format executed successfully.
----

[[GSADG1065]][[sthref24]]
Example 7-9 Setting the Log File Format using `set-log-attributes`

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

[source]
----
asadmin> set-log-attributes --target ManagedServer1 com.sun.enterprise.server.logging.GFFileHandler.formatter=ulf
com.sun.enterprise.server.logging.GFFileHandler.formatter logging attribute value set to ulf.
The logging attributes are saved successfully for ManagedServer1-config.
Command set-log-attributes executed successfully.
----

[[GSADG1066]]

See Also

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.

[[CEGGBJCC]][[GSADG1067]][[to-exclude-fields-in-log-records]]

===== To Exclude Fields in Log Records

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:

* `tid`
* `userId`
* `ecid`
* `timeMillis`
* `levelVal`

1. Ensure that the target server or cluster is running. Remote commands require a running server.

2. Exclude fields by using the link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`]
subcommand, specifying the following attribute and the fields to exclude:
+
[source]
----
com.sun.enterprise.server.logging.GFFileHandler.excludeFields=fields
----
where `fields` is a comma-separated list of the name-value fields to
exclude from the log file.

3. To apply your change, restart {productName}.

[[GSADG1068]][[sthref25]]
Example 7-10 Excluding Fields in Log Records

This example excludes the `userId` and `levelVal` name-value fields in
log records for standalone instance `ManagedServer1`:

[source]
----
asadmin> set-log-attributes --target ManagedServer1
com.sun.enterprise.server.logging.GFFileHandler.excludeFields=userId,levelVal
com.sun.enterprise.server.logging.GFFileHandler.excludeFields logging attribute value set to userId,levelVal.
The logging attributes are saved successfully for ManagedServer1-config.

Command set-log-attributes executed successfully.
----

[[GSADG1069]]

See Also

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

[[CEGBBEAH]][[GSADG1070]][[to-set-multiline-mode]]

===== To Set Multiline Mode

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.

1. Ensure that the target server or cluster is running. Remote commands require a running server.

2. Set multiline mode by using the
link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] subcommand, specifying the
following attribute and its value (`true` or `false`):
+
[source]
----
com.sun.enterprise.server.logging.GFFileHandler.multiLineMode=value
----

3. To apply your change, restart {productName}.

[[GSADG1071]][[sthref26]]
Example 7-11 Setting Multiline Mode

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

[source]
----
asadmin> set-log-attributes --target ManagedServer1
com.sun.enterprise.server.logging.GFFileHandler.multiLineMode=false
com.sun.enterprise.server.logging.GFFileHandler.multiLineMode logging attribute value set to false.
The logging attributes are saved successfully for ManagedServer1-config.

Command set-log-attributes executed successfully.
----

[[GSADG1072]]

See Also

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

[[gklni]][[GSADG00725]][[setting-log-file-rotation]]

==== Setting Log File Rotation

As explained in link:#ablul[Log Files], {productName} by default rotates log files when they reach 2 MB in size.
However, you can change the default rotation settings. For example, you
can change the file size at which the server rotates the log file or you
can configure a server to rotate log files based on a time interval. In
addition to changing when rotation occurs, you can also:

* Specify the maximum number of rotated files that can accumulate.
By default, {productName} does not limit the
number of rotated log files that are retained. However, you can set a
limit. After the number of log files reaches this limit, subsequent file
rotations delete the oldest rotated log file.

* Rotate the log file manually.
A manual rotation forces the immediate rotation of the target log file.

Changing the default log rotation settings is done using the
`set-log-attributes` subcommand, and rotating log files manually is done
using the `rotate-log` subcommand, as explained in the following
sections:

* link:#gkmbh[To Change the Rotation File Size]
* link:#gkman[To Change the File Rotation Interval]
* link:#gkmai[To Change the Limit Number of Retained Files]
* link:#gkmau[To Rotate Log Files Manually]

[[gkmbh]][[GSADG00380]][[to-change-the-rotation-file-size]]

===== To Change the Rotation File Size

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.

1. Ensure that the target server or cluster is running.

2. Change the rotation file size limit by using the
link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] subcommand,
specifying the following attribute and the desired limit in bytes:
+
[source]
----
com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes=bytes
----

3. To apply your change, restart {productName}.

[[GSADG00181]][[gkmay]]
Example 7-12 Changing the Rotation Size

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

[source]
----
asadmin> set-log-attributes --target ManagedServer1
com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes=1000000
com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes
logging attribute set with value 1000000.
These logging attributes are set for ManagedServer1.
ManagedServer1 :
com.sun.enterprise.server.logging.GFFileHandler.rotationLimitInBytes
logging attribute set with value 1000000.
These logging attributes are set for ManagedServer1.

Command set-log-attributes executed successfully.
----

[[GSADG868]]

See Also

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

[[gkman]][[GSADG00381]][[to-change-the-file-rotation-interval]]

===== To Change the File Rotation Interval

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`.

1. Ensure that the target server or cluster is running.

2. Change the rotation time limit by using the
link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] subcommand,
specifying the following attribute and the desired limit in minutes:
+
[source]
----
com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes=minutes
----

3. To apply your change, restart {productName}.

[[GSADG00182]][[gkmbc]]
Example 7-13 Changing the Rotation Interval

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

[source]
----
asadmin> set-log-attributes --target Cluster1
com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes=10
com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes
logging attribute set with value 10.
These logging attributes are set for Cluster1.
ClusterServer1 :
com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes
logging attribute set with value 10.
These logging attributes are set for Cluster1.

ClusterServer2 :
com.sun.enterprise.server.logging.GFFileHandler.rotationTimelimitInMinutes
logging attribute set with value 10.
These logging attributes are set for Cluster1.

Command set-log-attributes executed successfully.
----

[[GSADG869]]

See Also

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

[[gkmai]][[GSADG00382]][[to-change-the-limit-number-of-retained-files]]

===== To Change the Limit Number of Retained Files

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.

1. Ensure that the target server or cluster is running.
2. Change the limit number of retained log files by using the
link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] subcommand,
specifying the following attribute and the desired file limit number:
+
[source]
----
com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles=minutes
----
+
The behavior of the `com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles`
attribute is as follows:
+
* If the property is not set, {productName} keeps
  a maximum of 10 rotated log files.
* If the property is set to an invalid number or null, {productName} keeps a maximum of 10 rotated log files.
* If the property is set to 0, {productName}
  retains all rotated log files (that is, sets no maximum).

3. To apply your change, restart {productName}.

[[GSADG00183]][[gkmaq]]
Example 7-14 Changing the Limit Number of Retained Files

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

[source]
----
asadmin> set-log-attributes
com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles=10
com.sun.enterprise.server.logging.GFFileHandler.maxHistoryFiles
logging attribute set with value 10.
These logging attributes are set for server.
Command set-log-attributes executed successfully.
----

[[GSADG870]]

See Also

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

[[gkmau]][[GSADG00383]][[to-rotate-log-files-manually]]

===== To Rotate Log Files Manually

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
{productName} for changes to take effect.

1. Ensure that the target server or cluster is running.
2. Rotate log files by using the link:reference-manual/rotate-log.html#GSRFM00224[`rotate-log`]
subcommand.

[[GSADG00184]][[gkmav]]
Example 7-15 Rotating Log Files Manually

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.

[source]
----
asadmin> rotate-log --target ManagedServer2
Command rotate-log executed successfully.
----

[[GSADG871]]

See Also

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

[[gklnk]][[GSADG00726]][[adding-a-custom-logging-handler]]

==== Adding a Custom Logging Handler

By default, {productName} log records are
captured in a server log file using the format described in
link:#gkmex[Log Records]. However, you may find that you want to log
messages to a different location, such as a database or a remote server,
or log messages from specific loggers to your own file. This can be done
by implementing a custom log handler. This section explains how to add a
custom log handler to the {productName} logging
service.

[[ghmen]][[GSADG00384]][[to-add-a-custom-log-handler]]

===== To Add a Custom Log Handler

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:

[source]
----
handlers=java.util.logging.ConsoleHandler
----

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


[NOTE]
====
The custom handler class should be packaged in an OSGi module and the
JAR file placed in the as-install``/modules`` directory.
====


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.

[[GSADG872]]

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.

1. Ensure that the target server or cluster is running.
+
Remote subcommands require a running server.
2. Use the link:reference-manual/set-log-attributes.html#GSRFM00227[`set-log-attributes`] subcommand to add the
handler to the `handlers` attribute.
+
The default target of this subcommand is the DAS. Optionally you can
target a configuration, server, instance, or cluster.
3. To apply your changes, restart {productName}.
+
See link:domains.html#ginqj[To Restart a Domain].

[[GSADG00185]][[ghphb]]
Example 7-16 Adding a New Log Handler

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

[source]
----
asadmin> set-log-attributes
handlers=java.util.logging.ConsoleHandler,com.example.logging.MyHandler
handlers logging attribute set with value
java.util.logging.ConsoleHandler,com.example.logging.MyHandler.
These logging attributes are set for server.
Command set-log-attributes executed successfully.
----

[[GSADG873]]

See Also

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

[[gkobx]][[GSADG00556]][[viewing-log-records]]

=== Viewing Log Records

The recommended means for general viewing of logging information is to
use the Log Viewer in the Administration Console. The Log Viewer
simplifies reading, searching, and filtering log file contents. For
instructions, see the Administration Console online help.

{productName} also allows you to collect log
files into a ZIP archive, which provides the means to obtain and view
log files for an instance or cluster even when it is not currently
running. The following section explains how to collect all available log
files for an instance or cluster and compile them into a single ZIP
archive, which is done by using the `collect-log-files` subcommand.

[[gklbi]][[GSADG00385]][[to-collect-log-files-into-a-zip-archive]]

==== To Collect Log Files into a ZIP Archive

Use the `collect-log-files` subcommand in remote mode to collect log
files into a ZIP archive. The default target of this subcommand is the
DAS. Optionally you can target a configuration, server, instance, or
cluster.

1. Ensure that the target server or cluster is running.
+
Remote subcommands require a running server.
2. Use the link:reference-manual/collect-log-files.html#GSRFM00007[`collect-log-files`] subcommand to create
the ZIP archive.
+
The default location in which the ZIP archive is created is the
domain-dir`/collected-logs` directory. The `collect-log-files`
subcommand allows you to specify a nondefault directory in which the ZIP
archive is to be created by using the `--retrieve` option set to `true`,
followed by the directory name.
+
The name of the ZIP file contains the timestamp, as follows:
+
`log_`yyyy-mm-dd_hh-min-sec`.zip`

[[GSADG00186]][[gklap]]
Example 7-17 Creating a ZIP Archive

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

[source]
----
asadmin> collect-log-files --target MyCluster
--retrieve true /space/output
Log files are downloaded for ClusterServer1.
Log files are downloaded for ClusterServer2.
 Created Zip file under /space/output/log_2011-02-10_13-35-25.zip.
Command collect-log-files executed successfully.
----

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

[source]
----
as-install-parent/
  glassfish/
    domains/
      domain-dir/
        collected_logs/
          logs/
            ClusterServer1/
              server.log
            ClusterServer2/
              server.log
----

[[GSADG874]]

See Also

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

[[CEGGHGIJ]][[GSADG1073]][[listing-loggers]]

=== Listing Loggers

You can list and view information about all public loggers in your
distribution of {productName}.

[[CEGGICGF]][[GSADG1074]][[to-list-loggers]]

==== To List Loggers

Use the `list-loggers` subcommand in remote mode to list the logger
name, subsystem, and description of loggers in your distribution of
{productName}. Internal loggers are not listed.

1. Ensure that the target server or cluster is running. Remote commands require a running server.
2. List loggers by using the link:reference-manual/redeploy.html#GSRFM00217[`list-loggers`]
subcommand.

[[GSADG1075]][[sthref27]]
Example 7-18 Listing Loggers

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

[source]
----
asadmin> list-loggers
Logger Name                            Subsystem         Logger Description
...
jakarta.enterprise.monitoring            Monitoring        Monitoring Logger
jakarta.enterprise.system.core.ee        AS-CORE           Jakarta EE Core Kernel
jakarta.enterprise.system.jmx            JMX               JMX System Logger
jakarta.enterprise.system.tools.admin    ADMIN             Administration Services
...
Command list-loggers executed successfully.
----

[[GSADG1076]]

See Also

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