Configuring Logging

Terminology: In log4j, a 'logger' is a named entity. Logger names are case-sensitive and they follow a hierarchical naming standard. For example, the logger named com.foo is a parent of the logger named com.foo.bar.

Temporarily change logging behaviour while Confluence is running

When troubleshooting a problem, you can temporarily change the logging behaviour while Confluence is running.  These changes aren't written to the log4j.properties file so are discarded when you next stop Confluence.

Change the logging level of an existing class or package

You need System Administrator global permissions to do this. See log4j Logging Levels for information on the specific levels. 

To change the logging level of an existing class or package:

1. Go to Administration menu , then General Configuration. > Logging and Profiling.
2. If you run Confluence in a cluster, select a cluster node.
3. Locate the relevant class or package, and select a value from the New Level dropdown.
4. Save your changes.

Alternatively, choose Remove if you want to stop logging a particular class or package.

Remember, your changes will not be written to the log4j.properties file so will be discarded when you next stop Confluence.

Add logging for an additional class or package

Sometimes our support team may ask you to enable some additional logging when troubleshooting a specific problem. You need System Administrator global permissions to do this. 

To set the logging level for a new class or package:

1. Go to Administration menu , then General Configuration. > Logging and Profiling.
2. If you run Confluence in a cluster, select a cluster node.
3. Enter the name in the Class/Package name field.  It will be something like com.atlassian.confluence.example.
4. Select Add entry to add the new class or package to the list.
5. Locate the relevant class or package, and select a value from the New Level dropdown.
6. Save your changes.

Turn page profiling on or off

See Troubleshooting Slow Performance Using Page Request Profiling for more information on when and how to use page profiling. 

Turn detailed SQL logging on or off

See Enabling Detailed SQL Logging for more information on when and how to use detailed SQL logging.

Preset logging configurations

Confluence provides two preset log configurations:

• Production
  This is the recommended default configuration, which aims to provide the most important information without flooding your logs. 
• Diagnostic
  This changes the logging level of most packages to debug. It can be useful when troubleshooting, but results in slower performance and will fill up your log files more quickly.

If you want to reset your logging configuration to the default, select Production.

Screenshot: Changing Log Levels and Profiling 

Permanently change logging level in the properties file

You need access to the installation directory to do this. 

The log4j.properties file lists all the default classes and packages, plus some additional packages that you can choose to enable. 

 To permanently change the logging level of a class or package:

1. Stop Confluence.
2. Edit the <CONFLUENCE-INSTALL>/confluence/WEB-INF/classes/log4j.properties file.
3. Under Logging Levels, locate the package you want to change. Remove the # symbol to uncomment the package if necessary.

4. Change the logging level to DEBUG, INFO, WARNING, ERROR, or FATAL. See log4j Logging Levels for accepted values. For example:
   
   

   log4j.logger.com.atlassian.confluence.cache=DEBUG

5. Save the file, and restart Confluence for the changes to take effect.

If you're running Confluence in a cluster, you will need to repeat your change on every node. You can take each node down one by one, there's no need to stop the whole cluster.

If you want to log a class or package that's not already listed, simply add it to the file.  See the log4j documentation for more information. 

If you want to change the location, number, or size of the logs, see Working with Confluence Logs.

Configure levels for java.util.logging in logging.properties

Confluence uses a few libraries that use java.util.logging rather than log4j or slf4j. These libraries include:

• com.sun.jersey
• org.apache.shindig

Confluence's logging.properties file is set to redirect java.util.logging at specific levels to log4j via slf4j.

To increase logging levels for these libraries, you must first configure the logging.properties file in <CONFLUENCE-INSTALL>/confluence/WEB-INF/classes/. The logging levels are different from log4j. See java.util.logging in the Java 11 documentation for further instructions.

For example, to increase logging for shindig, change the following line in the logging.properties file:

org.apache.shindig.level = INFO

to

org.apache.shindig.level = FINE

And then use one of the methods above as well to configure the log4j level.

Configure burst limiting for loggers

Confluence allows burst limiting on loggers by using the log4j2 BurstFilter implementation. Learn more about this mechanism

To add burst limiting to a specific logger:

1. Stop Confluence.
2. Edit the \<CONFLUENCE-INSTALL>/confluence/WEB-INF/classes/burstFilterConfiguration.properties file.

3. Configure the file by using the following configuration as an example, where:

   1. loggerId is an arbitrary id for the logger that you'll attach the filter to.

   2. loggerName is the class name of the logger.
   3. level is the log level at which we filter logs; anything at or below this level will be subject to filtering.
   4. rate is the average number of events we allow per second.

   5. maxBurst is the max number of events that can occur before filtering starts. 

      burstFilter.{loggerId}={loggerName}  
      burstFilter.{loggerId}.maxBurst=5  
      burstFilter.{loggerId}.rate=0.5F  
      burstFilter.{loggerId}.level=WARN

      For example: 

      burstFilter.analyticsLogger=com.atlassian.analytics.client.pipeline.PipelineExecutionService  
      burstFilter.analyticsLogger.maxBurst=5  
      burstFilter.analyticsLogger.rate=0.5F  
      burstFilter.analyticsLogger.level=WARN

4. Save the file, and restart Confluence for the changes to take effect.