Using log4j to Configure mailboxd Logging
Using log4j to Configure mailboxd Logging
|
Enabling DEBUG log level will log sensitive information including authentication tokens, do not turn on DEBUG log in production. If you have to enable debug log make sure to take proper steps to destroy logs afterwards. |
The Zimbra server uses log4j, a Java logging package, as the log manager for mailboxd. By default, the Zimbra server has log4j 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 log4j, see the Apache log4j documentation.
This article outlines how to use log4j to configure log4j 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.
log4j 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 log4j 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 8.6 :
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 log4j configuration file:
log4j.logger.zimbra.<category name>=DEBUG
For example, the following enables DEBUG level logging for the zimbra.mailbox category:
log4j.logger.zimbra.mailbox=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 |
|---|---|
| log4j.logger.zimbra | 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 log4j.logger.zimbra | 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 LOGFILE directs output from the log4j.logger.zimbra category to be written to /opt/zimbra/log/mailbox.log.
log4j.logger.zimbra=INFO, LOGFILE
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 log4j.logger.zimbra category is writing logging events to the both LOGFILE and to SYSLOG appenders.
log4j.logger.zimbra=INFO, LOGFILE, SYSLOG
Adding another appender in addition to LOGFILE 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.
Using DEBUG log level with Zimbra Extensions
To enable the storing of debug level messages for extensions append to /opt/zimbra/conf/log4j.properties.in and /opt/zimbra/conf/log4j.properties the following:
logger.extensions.name = zimbra.extensions logger.extensions.level = debug logger.extensions.additivity = false logger.extensions.appenderRef.LOGFILE.ref = mailboxFile
You will have to restart Zimbra using:
sudo su zimbra - zmmailboxdctl restart
You can now use the following:
ZimbraLog.extensions.debug("this is a debug message that will show up in /opt/zimbra/log/mailbox.log if debug logging level is set for extensions");
This will show up in the /opt/zimbra/log/mailbox.log like this:
2022-10-26 11:12:25,174 DEBUG [qtp48914743-18:https://zimbra10.barrydegraaff.nl/service/extension/mytest] [] extensions - this is a debug message that will show up in /opt/zimbra/log/mailbox.log if debug logging level is set for extensions
Nginx debug logging
https://wiki.zimbra.com/wiki/How_to_enable_debug_logging_for_nginx
Help not all mailbox logs are being logged
In case you have set the debug level on mailbox, and you still see no or not all logging, make sure you have set-up DNS correctly. See: https://wiki.zimbra.com/wiki/DNS Verify using dig and ip commands that the IP of your server matches DNS!
dig A zimbra-mbox-server.example.com ip a
Related Articles
