Log4j2

Using log4j2 to Configure mailboxd Logging

   KB 24435        Last updated on 2022-06-18  




0.00
(0 votes)

From 9.0.0-Patch-25 and 8.8.15-Patch-32 onwards, Log4j has been upgraded to version 2.17.1. The Zimbra server now uses log4j2, a Java logging package, as the log manager for mailboxd. By default, the Zimbra server has log4j2 configured to log to the local file system. You can configure log4j to direct output to a variety of other locations. For more information on log4j2, see the Apache log4j2 documentation.

This article outlines how to use log4j2 to configure log4j2 categories, log output, logging levels.

Note: This article is only relevant to logging for mailboxd. For information on other Zimbra log files, see Log Files.

log4j2 Configuration File

Errors, warnings and other logging events are logged by category. For example, an IMAP error will be logged to the log4j.logger.zimbra.imap sub-category. The category settings in log4j2 are stored in two configuration files.

Temporary Logger Level Changes - /opt/zimbra/conf/log4j.properties

/opt/zimbra/conf/log4j.properties allows you to make a temporary changes to the logging level. Any changes to /opt/zimbra/conf/log4j.properties will be reset by the configurations stored in /opt/zimbra/conf/log4j.properties.in after the mailboxd service has been restarted.

In 7.x and earlier releases, the server side logging controlled in log4j.properties was automatically scanned and reloaded even when the server is running.

In 8.+ it is now necessary to invoke zmprov rlog [see next section below] from the command line in order to cause log4j.properties to be reloaded while server is running. Bug 75505

Permanent Logger Level Changes - /opt/zimbra/conf/log4j.properties.in

To make permanent changes to the configuration file, make changes to /opt/zimbra/conf/log4j.properties.in, and either run zmmailboxdctl restart or restart the server using zmcontrol restart .

Commands To Change Logger Options Per Account vs Server

From ZCS 9.0.0-Patch-25 and 8.8.15-Patch-32 :

zmprov help log

  addAccountLogger(aal) [-s/--server hostname] {name@domain|id} {logging-category} {trace|debug|info|warn|error}

  getAccountLoggers(gal) [-s/--server hostname] {name@domain|id}

  getAllAccountLoggers(gaal) [-s/--server hostname]

  removeAccountLogger(ral) [-s/--server hostname] [{name@domain|id}] [{logging-category}]

  resetAllLoggers(rlog) [-s/--server hostname]

    Log categories:
        zimbra.account     - Account operations
        zimbra.acl         - ACL operations
        zimbra.activity    - Document operations
        zimbra.autoprov    - Auto provision operations
        zimbra.backup      - Backup and restore
        zimbra.cache       - In-memory cache operations
        zimbra.calendar    - Calendar operations
        zimbra.datasource  - Data Source operations
        zimbra.dav         - DAV operations
        zimbra.dbconn      - Database connection tracing
        zimbra.doc         - Docs operations
        zimbra.ews         - EWS operations
        zimbra.extensions  - Server extension loading
        zimbra.filter      - Mail filtering
        zimbra.gal         - GAL operations
        zimbra.im          - Instant messaging operations
        zimbra.imap        - IMAP server
        zimbra.imap-client - IMAP client
        zimbra.index       - Indexing operations
        zimbra.io          - Filesystem operations
        zimbra.ldap        - LDAP operations
        zimbra.lmtp        - LMTP server (incoming mail)
        zimbra.mailbox     - General mailbox operations
        zimbra.mailop      - Changes to mailbox state
        zimbra.milter      - MILTER protocol operations
        zimbra.misc        - Miscellaneous
        zimbra.nginxlookup - Nginx lookup operations
        zimbra.pop         - POP server
        zimbra.pop-client  - POP client
        zimbra.purge       - Mailbox purge operations
        zimbra.redolog     - Redo log operations
        zimbra.search      - Search operations
        zimbra.security    - Security events
        zimbra.session     - User session tracking
        zimbra.smtp        - SMTP client (outgoing mail)
        zimbra.soap        - SOAP protocol
        zimbra.sqltrace    - SQL tracing
        zimbra.store       - Mail store disk operations
        zimbra.sync        - Sync client operations
        zimbra.system      - Startup/shutdown and other system messages
        zimbra.zimlet      - Zimlet operations

log4j Categories

Enabling DEBUG in the appropriate sub-category can help you identify a problem. If you do not know what sub-category to enable, you can enable DEBUG in log4j.logger.zimbra, however this will generate logging events for every single subcategory. This is a very large amount of logging events and can take a long time to read through. For this reason, it is always advisable to enable DEBUG or another logging level in a specific sub-category. To enable logging for a specific category, add the following to the end of the log4j2 configuration file:

  logger.<category name>.name = zimbra.<category name>
  logger.<category name>.level = DEBUG

For example, the following enables DEBUG level logging for the zimbra.mailbox category:

logger.zimbra.name = zimbra.mailbox
logger.zimbra.level = debug


Note: Review the configuration file to see if the category you are enabling is already listed. If a category is listed twice, and both instances have the same appender, it will log each event twice.

Predefined log4j Categories in ZCS

The following table contains a list of log4j categories which are predefined in the Zimbra Collaboration Suite.

Note: You can also find information on predefined log4j categories in zmprov help log.

Category Description
logger.zimbra.name Parent logger category. Records log events for all of the following child categories. By default, this category is set to the INFO log level.
Sub-categories of logger.zimbra.name Description
zimbra.account Account operations
zimbra.acl ACL operations
zimbra.backup Backup and restore
zimbra.cache In-memory cache operations
zimbra.calendar Calendar operations
zimbra.dav DAV operations
zimbra.dbconn Database connection tracing
zimbra.extensions Server extension loading
zimbra.ews EWS operations - ZCS 8.5+
zimbra.filter Mail filtering
zimbra.gal GAL operations
zimbra.imap IMAP protocol operations
zimbra.index Index operations
zimbra.io File system operations
zimbra.ldap LDAP operations
zimbra.lmtp LMTP operations (incoming mail)
zimbra.mailbox General mailbox operations
zimbra.misc Miscellaneous
zimbra.op Changes to the mailbox state
zimbra.pop POP protocol operations
zimbra.redolog Redo log operations
zimbra.security Security events
zimbra.session User session tracking
zimbra.smtp SMTP operations (outgoing mail)
zimbra.soap SOAP protocol
zimbra.sqltrace SQL tracing
zimbra.store Mail store disk operations
zimbra.sync Sync client operations
zimbra.system Start-up/shutdown and other system messages
zimbra.wiki Wiki operations
zimbra.zimlet Zimlet operations

Logging Levels

Logging levels determine what types of events are logged. The following are logging levels in log4j:

  • FATAL
  • ERROR
  • WARN
  • INFO
  • DEBUG

The FATAL logging level will only log very severe error events. The DEBUG logging level will log detailed informational events useful for debugging purposes. Each additional logging level will log more events, including the events belonging to the previous logging levels. For example, enabling the WARN logging level will record log events belonging to the FATAL, ERROR, and WARN logging levels, but will not record events belonging to the INFO or DEBUG levels. By default, most predefined log4j categories in ZCS are set to the INFO logging level.

For more information on logging levels, see the ZCS Admin Guide > Monitoring Zimbra Servers > Log Files > Logging Levels.

Protocol Trace

Protocol trace applies to ZCS 7 and is available in the following logging categories with TRACE logging level:

  • zimbra.smtp
  • zimbra.lmtp
  • zimbra.soap
  • zimbra.imap
  • zimbra.imap-client
  • zimbra.pop
  • zimbra.pop-client
  • zimbra.sync

Log Output

Log output is directed to a log file by an appender. If an appender is not specified for a category, it inherits the appender of its parent category. By default, log output is directed to /opt/zimbra/log/mailbox.log. Additionally, Syslog captures FATAL and ERROR level events.

You can configure the log4j configuration file to direct log output to other predefined appenders, or even to user-defined appenders.

In the following example, the appender logger.sync.appenderRef.SYNC.ref directs output from the zimbra.sync category to be written to /opt/zimbra/log/sync.log.

appender.SYNC.type = RollingFile
appender.SYNC.name = syncFile
appender.SYNC.fileName = /opt/zimbra/log/sync.log
appender.SYNC.filePattern = /opt/zimbra/log/sync.log.%d{yyyy-MM-dd}
appender.SYNC.layout.type = PatternLayout
appender.SYNC.layout.pattern = %d %-5p [%t] [%z] %c{1} - %m%n
appender.SYNC.policies.type = Policies
appender.SYNC.policies.time.type = TimeBasedTriggeringPolicy
appender.SYNC.policies.time.interval = 2
appender.SYNC.policies.time.modulate = true
appender.SYNC.strategy.type = DefaultRolloverStrategy
logger.sync.name = zimbra.sync
logger.sync.level = trace
logger.sync.additivity = false
logger.sync.appenderRef.SYNC.ref = syncFile


Changing the appender LOGFILE to a different predefined appender will cause the category to stop writing to LOGFILE and to begin writing to the new location.

You can also direct log output for a specific category to multiple appenders. In this example, the zimbra.sync category is writing logging events to the both syncFile and to syncTraceFile appenders.

logger.sync.name = zimbra.sync
logger.sync.level = trace
logger.sync.additivity = false
logger.sync.appenderRef.SYNC.ref = syncFile
logger.sync.appenderRef.SYNCTRACE.ref = syncTraceFile


Adding another appender in addition to syncFile can be useful if you want to first quickly identify relevant logging events from a particular child category, and then review them with other logging events from other categories.

Related Articles

Verified Against: ZCS 6.0 and ZCS 7.0 Date Created: 3/1/2010
Article ID: https://wiki.zimbra.com/index.php?title=Log4j2 Date Modified: 2022-06-18



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search