Logging and Profiling
When troubleshooting problems with your Crowd installation, it is often useful to change the level of information provided by your Crowd server so that more information, messages and warnings are shown than usual. This page describes how to:
- Adjust the settings which affect Crowd's logging.
- Enable performance profiling. With performance profiling turned on, your system output console will show a record of the time it takes (in milliseconds) to complete each Crowd action. This will help with diagnosing performance problems. The resulting output will be large, so you should not enable it for long periods. You can see an example of performance profiling output here.
Summary of the Logging Levels
Crowd uses Apache's log4j logging service. The amount of information written to the log file is determined by the logging 'level'. The type of message output at each level is as follows:
Level | Type of Message Written to the Log |
|---|---|
DEBUG | Used to troubleshoot SSO problems only. These are low-level details that most people never need to know about. NOTE: This setting may cause user passwords to be logged. |
INFO | Informational messages about what Crowd is doing. Usually not interesting. |
WARN | Warnings that something may have gone wrong, or other messages a system administrator may wish to know. These are conditions that, while not errors in themselves, may indicate that the system is running sub-optimally. |
ERROR | Indications that something has gone wrong in Crowd. The person responsible for configuring Crowd should be notified. |
FATAL | Indications that something has gone wrong so badly that the system cannot recover. |
ALL | All possible log messages. |
Finding the Crowd Log File
When you report a problem to Atlassian Support, we may ask you to send us your atlassian-crowd.log file. The location of the log file may vary, depending on your Crowd installation type. Provided that you have not changed the log file location from the default, the Crowd log file is at the location described below.
Installation Type | Location of Log File |
|---|---|
Crowd Standalone edition | Crowd 2.0.3 and older versions: In the root directory of your Crowd application, e.g. |
Crowd Standalone running as a Windows service |
|
Changing the Log Settings
You can change the log settings in two ways:
- Set the logging levels at runtime via the Administration Console, as described immediately below. Your changes will be in effect only until you next restart Crowd.
- Edit the log configuration file, as described in the Advanced section below. Your changes will take effect next time you start Crowd, and for all subsequent sessions.
Crowd Data Center
For Crowd Data Center, you'll need to change the log settings on each node.
Configuring the Log Settings and Performance Profiling via the Administration Console
If necessary, you can edit the configuration file directly
If you change the log settings via the Administration Console, the changes are not written to the log4j.properties file and are therefore discarded when you next stop Crowd. Also, not all logging behavior can be changed via the Administration Console. For logging configuration not mentioned below, or to change the log settings permanently, you will need to stop Crowd and then edit the log configuration file instead.
The 'Logging & Profiling' screen tells you whether performance profiling is currently on or off, and shows a list of all currently defined loggers. On this screen you can:
- Turn performance profiling on or off. With performance profiling turned on, your system output console will show a record of the time it takes (in milliseconds) to complete each Crowd action. This will help with diagnosing performance problems. The resulting output will be large, so you should not enable it for long periods. You can see an example of performance profiling output here.
- Set the logging level for each class or package name, or reset all logging levels to the default setting.
Refer to the section on logging levels above. Any changes made in this way will apply only to the currently-running Crowd lifetime.
To configure profiling and logging,
- Log in to the Crowd Administration Console.
- In the top navigation bar, click
> Logging & Profiling.
The Logging and Profiling screen appears, as shown below. The screen has the following sections:- Performance Profiling — Click the Enable Profiling button to turn profiling on, or Disable Profiling' to turn it off. (You will only see one of these buttons.)
- Log4j Logging — This section shows the loggers currently in action for your Crowd instance.
- You can change the logging level by selecting a value from the New Level dropdown list. Above is a definition of each level. You can also read the Apache documentation for more information.
- You can click the Revert to Default button if you want to reset the logging levels to the values shipped with your Crowd installation.
- Click the Update Logging button to save any changes you have made in the Log4j Logging section.
Description of the loggers:
Logger | Description |
|---|---|
| This is the parent of the crowd package loggers. Any children which do not have a level assigned to them will inherit the level from their parent. This logger should be set to DEBUG only if you are investigating SSO issues. |
| Can be helpful if a Crowd SOAP service fault is thrown. It is best to enable DEBUG for all three XFire classes simultaneously when troubleshooting Crowd's SOAP service. |
| The Crowd server outputs the incoming SOAP request method and parameters. This is useful when debugging your applications or monitoring the level of traffic for an integrated application. |
| The Crowd server outputs the outgoing SOAP request method and parameters. This is useful when debugging your applications or monitoring the level of traffic for an integrated application. |
| Useful for troubleshooting certain licensing issues in Crowd. |
| Can be helpful for troubleshooting startup errors in Crowd. |
| This is the root of the logger hierarchy, i.e. it is the parent of all loggers. The level assigned to the root will be the default level for any loggers which do not have a specific level and do not inherit from another parent. |
Advanced Log Configuration
Terminology: In log4j, a 'logger' is a named entity. Logger names are case sensitive and follow a hierarchical naming standard. For example, the logger named com.foo is a parent of the logger named com.foo.Bar.
Finding the Log Configuration File
Crowd's logging behavior is defined in the following properties file:
- For Crowd installations: {
CROWD-INSTALL}/crowd-webapp/WEB-INF/classes/log4j.properties
This file is a standard log4j configuration file, as described in the Apache log4j documentation.
Editing the Log Configuration File
To configure the logging levels and other settings on a permanent basis:
- Stop Crowd.
- With a text editor, open the
log4j.propertiesfile in the location described above. - Adjust the output level to the required level of importance listed in the section on levels above.
- Save the
log4j.propertiesfile. - Restart Crowd to have the new log settings take effect.
When diagnosing a server problem you need to adjust Crowd's package logging to:log4j.logger.com.atlassian.crowd=DEBUG
Changing the Destination of the Crowd Log File
Terminology: In log4j, an output destination is called an 'appender'.
To change the destination of the Crowd log file:
- Stop Crowd.
- With a text editor, open the
log4j.propertiesfile in the location described above. - Look for the
org.apache.log4j.RollingFileAppenderentry in the 'Log File Locations' section of the file. This appender controls the default logging destination described above. - Edit the following line, and replace
atlassian-crowd.logwith the full path and file name for the required logging destination:log4j.appender.filelog.File=atlassian-crowd.log. - Save the
log4j.propertiesfile. - Restart Crowd to have the new log settings take effect.
Note: If you change the location of your log files, they will no longer be included when you generate a support zip. This means you'll need to attach your logs to any support requests manually.