This page last changed on Sep 02, 2009 by alui.
On this page:
Logging
JIRA uses a powerful logging module called log4j for runtime logging.
There are five logging levels available in log4j: 'DEBUG', 'INFO', 'WARN', 'ERROR' and 'FATAL'. Each logging level provides more logging information that the level before it:
'DEBUG' < 'INFO' < 'WARN' < 'ERROR' < 'FATAL'
'DEBUG' provides the most verbose logging and 'FATAL' provides the least verbose logging.
The default logging levels can be changed either;
- temporarily — your change to the logging level will not persist after you next restart JIRA, or
- permanently — your change to the logging level will persist, even after you restart JIRA.
For example, when troubleshooting, you might temporarily change the logging level from 'WARNING' to 'INFO' so as to get a more detailed error message or a stack trace. If you are unsure of which logging categories to adjust, the most helpful information generally comes from the log4j.rootLogger category and the log4j<category>.com.atlassian categories.
To temporarily change the logging level:
- Log in as a user with the 'JIRA System Administrators' global permission.
- Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
- Under the 'System' sub-menu in the left-hand navigation column, click the 'Logging & Profiling' link.
- The 'Logging & Profiling' page will display. This lists all the defined log4j categories and their current logging levels. To edit the logging level of a category, click the 'Edit' link next to the category in the list.
- Choose the new logging level for the category, then click 'Update'.
To permanently change the logging level:
- Edit the log4j.properties file, which is found in the WEB-INF/classes/ directory under the JIRA web application directory.
 | The log4j.properties file that ships with JIRA has the default logging levels specified. For more information about log4j (e.g. how to define new logging categories), and about the format of the log4j.properties file, please refer to the documentation on the log4j site. |
- Restart JIRA.
 | If your application server itself configures logging (e.g. JBoss), you may need to remove the log4j.properties file. On some servers (e.g. JBoss 3.0), you may also need to remove the entire log4j.jar file to get logging to work. |
Profiling
If you are experiencing performance issues with JIRA, it is often helpful to see where the slow-downs occur. To do this you can enable profiling as described below, and then analyse the performance traces that JIRA will produce for every request. An example of a profiling trace is shown below:
[Filter: profiling] Turning filter on [jira_profile=on]
[116ms] - /secure/Dashboard.jspa
[5ms] - IssueManager.execute()
[5ms] - IssueManager.execute()
[5ms] - Searching Issues
[29ms] - IssueManager.execute()
[29ms] - IssueManager.execute()
[29ms] - Searching Issues
[28ms] - Lucene Query
[23ms] - Lucene Search
Profiling can be enabled either;
- temporarily — profiling will be enabled until you next restart JIRA, or
- permanently — profiling will remain enabled, even after you restart JIRA.
To temporarily enable profiling:
- Log in as a user with the 'JIRA System Administrators' global permission.
- Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
- Under the 'System' sub-menu in the left-hand navigation column, click the 'Logging & Profiling' link.
- The 'Logging & Profiling' page will display. Scroll to the bottom of the screen. The 'Profiling' section will inform you whether profiling is currently turned 'ON' or 'OFF', and will also show or hide the 'Disable profiling' and 'Enable profiling' links respectively.
- To turn Profiling 'ON', click the 'Enable profiling' link. JIRA will start generating profiling traces in its log.
- To turn Profiling 'OFF', click the 'Disable profiling' link.
To permanently enable profiling:
- Edit atlassian-jira/WEB-INF/web.xml (if you are using JIRA Standalone) or webapp/WEB-INF/web.xml in your JIRA installation directory (if you are using JIRA EAR/WAR).
- Find the following entry:
<filter>
<filter-name>profiling</filter-name>
<filter-class>com.atlassian.jira.web.filters.JIRAProfilingFilter</filter-class>
<init-param>
<!-- specify the which HTTP parameter to use to turn the filter on or off -->
<!-- if not specified - defaults to "profile.filter" -->
<param-name>activate.param</param-name>
<param-value>jira_profile</param-value>
</init-param>
<init-param>
<!-- specify the whether to start the filter automatically -->
<!-- if not specified - defaults to "true" -->
<param-name>autostart</param-name>
<param-value>false</param-value>
</init-param>
</filter>
- Modify the autostart parameter to be true instead of false. That is:
<init-param>
<!-- specify the whether to start the filter automatically -->
<!-- if not specified - defaults to "true" -->
<param-name>autostart</param-name>
<param-value>true</param-value>
</init-param>
- Save the file. If you are running JIRA Standalone this is all you have to do. Profiling will be enabled when you restart JIRA.
- If you are running JIRA EAR/WAR, re-build and re-deploy the JIRA web application using the build script and the instructions for your application server.
|