Overview

Starting from Jira Data Center 11.2, OpenSearch is a fully supported external search and index platform. Jira sends index operations to an OpenSearch cluster and a built-in consistency checker verifies that recent database changes are in OpenSearch. Reindexing builds a new staging index and promotes it with an alias. This allows people to keep searching while a rebuild runs.

OpenSearch versus Lucene - what you need to know

• Where the index lives
  OpenSearch stores Jira issue documents in an external cluster. This can be a self-managed OpenSearch cluster or a managed service. Jira nodes no longer keep full local copies of the issue index.

• Index aliasing and reindexing
  Jira builds a new staging index and promotes it by switching an alias to the rebuilt index. Search stays available during a reindex.

• Consistency checking
  A scheduled job checks that updates recorded in Jira’s database exist in OpenSearch with the correct version. By default, this happens every minute. If Jira detects gaps, it replays missed operations to restore consistency.

• Common limits and behaviors
  OpenSearch mappings and field-count limits apply. Result-window limits protect memory, and requests have content-length enforcement. Search happens in near real time, which can introduce short-lived delays for cross-session visibility.

Indexing recommendations for OpenSearch

• Follow Jira OpenSearch hardware guidance and monitor cluster health, node CPU and memory, heap, disk I/O, and query latency.

• Define the number of shards and replicas, refresh interval, and other index-level settings in an index template. This ensures they persist across rebuilds. How to configure index settings on OpenSearch.

• Increase consumer threads and batch size gradually. Monitor the database load, OpenSearch ingestion latency, and Jira node resources. Reduce these values if you see errors, database saturation, or OpenSearch backpressure.

• Keep Jira’s maximum payload size below the OpenSearch cluster max_content_length to avoid HTTP 413 or 513 errors. Use the Jira property to cap payloads when needed.

Identify high-impact custom fields

To identify custom fields with the longest indexing times:

1. Go to the Clustering screen.

2. Select a node and select Actions > Custom field indexing.

View the custom fields that take longest to index

Debugging indexing with OpenSearch

When troubleshooting indexing and search issues with OpenSearch, focus on:

• the connection between Jira and OpenSearch

• cluster health and mappings

• write behavior

• consistency replay

Where the index lives and how to inspect it

• Physical location: Issue documents are stored in the OpenSearch index (for example, indexes matching jira-issues*). Jira points all reads and writes at an alias (for example, jira-issues-<timestamp>) which moves during reindex promotion.

• Verification checkpoints:

  • System information shows search.platform=opensearch (in Administration > System > System info).

  • Atlassian Troubleshooting and Support Tools (ATST) provides OpenSearch connectivity and specific mapping health checks.

Useful logging and signals

• Look for OpenSearch client errors, bulk indexing outcomes, index consistency check logs, payload-too-large errors, version conflicts, and retry messages in the Jira log (atlassian-jira.log)

• Use OpenSearch APIs or dashboards to monitor OpenSearch. Check the cluster state, shard allocation, indexing backpressure, and slow logs.. How to monitor OpenSearch

• You can set the classes below to DEBUG to get more detailed information. This significantly increases log verbosity, so set these back to WARN when you're finished. Change logging levels in Jira Data Center

 com.atlassian.jira.search.opensearch 
 com.atlassian.jira.search.opensearch.OpenSearchIndexWriter
 com.atlassian.jira.search.opensearch.OpenSearchRetryRegistryFactory

Common OpenSearch errors and fixes

Handling reindexing with OpenSearch

When you trigger a full reindex, Jira creates a fresh staging index in OpenSearch. It indexes all issues, then applies any missed changes captured during the run, and promotes the staging index to production by switching the alias. You can cancel a running reindex without disrupting ongoing searches.

• Throughput tuning: Adjust Jira reindex consumer threads and bulk request size to balance speed against database, network, and OpenSearch capacity. Monitor the indexing rate and bulk latencies in logs and OpenSearch dashboards.

• Fault tolerance during reindex: Jira retries transient failures and allows a small failure tolerance threshold if configured. If the threshold is exceeded, the reindex cancels. Identify failed documents in logs and fix the issues before retrying.

More about reindexing in OpenSearch