Documentation for JIRA 4.0. Documentation for other versions of JIRA is available too.

Skip to end of metadata
Go to start of metadata

Overview

Indexing in JIRA is performed by Lucene a high-performance, full-featured text search engine library.

What you need to know

JIRA will perform partial re-indexes of the Lucene index after every issue change, this is handled by the Issue Index Listener viewable in Administration > System > Listeners.

It is also possible to run a complete re-index on demand by running a manual re-index from Administration > System > Indexing. From this location you can also specify a new location for JIRA's index files.

Indexing recommendations

We really only have one major recommendation when it comes to indexing:

Golden Rule

Icon

The file path that you specify for JIRA's indexes must be located on a fast local disk.

If JIRA is accessing its indexes across a network drive, Samba or NFS mount you are going to run into indexing exceptions, this would be a likely exception:

2006-03-28 13:06:05,540 ERROR [jira.issue.index.DefaultIndexManager] Giving up reindex - waited 10 seconds
com.atlassian.jira.issue.index.IndexException
...

So you should never run JIRA with this type of configuration.

Indexing errors

Locking Exception

This can occur when another process has a lock on the index, possible causes of this are:

  • There is a lock file left on disk from a previous unclean restart.
  • An old JIRA instance still has threads running; possibly from an earlier JIRA instance that was not entirely shut down when JIRA was last restarted.
  • A process from the current JIRA instance that is taking an unusually long time (10+seconds) finishing.

If your logs mention a .lock file the safest solution is too:

  1. Stop JIRA
  2. Delete the .lock files
  3. Restart JIRA
  4. Perform a full re-index.

These lock files (if you are running JIRA standalone) will be in Tomcat's temp directory. If you need some extra information finding these lock files it may help to have a quick read of the F.A.Q. article on the Lucene wiki.

Timeout Exceptions

Increase the index wait time

If you are seeing exceptions similar to the example above there may be some contention for the lucene indexes. The first option is to increase the allowable timeout for obtaining a lock.

This is done by modifying the jira-application.properties file, specifically the value:

Take a thread dump

JIRA v3.7 and later will automatically perform do a thread dump into the log file in the event of index lock timeouts. If the above does not work and you are still seeing these exceptions it is time to create a support request and attach a thread dump when this error is occurring. Hopefully this thread dump will show what JIRA is currently waiting on to grab the lock on the indexing files.

Poor Indexing Performance

If indexing performance is poor, the typical result is slow response times and index timeouts. Index timeouts will result in potentially out-of-date issue results from searches and in issue navigator and portlets.

Note that poor indexing performance is typically the result of poor disk performance. Note also that an overwhelmingly common cause of poor disk performance on MS Windows is anti-virus software. Understandably, many customers find it difficult to understand how many anti-virus products can continue to have a serious negative impact on disk performance even when the antivirus software is disabled. Nevertheless, it is sometimes necessary to completely uninstall anti-virus software in order to correctly assess the impact it has on disk performance and JIRA indexing. Many anti-virus products can exclude designated directories from close, performance degrading monitoring. The JIRA index directory would be an ideal candidate for such an exclusion.

You can use our disk access speed utility to determine if disk performance is a problem for you. Compare the results you get to our published Good results in that page.