[Internal]: Document synonyms filter circuit breaker behavior

[Mikep86]

Description

In ES 9.4 and serverless, we added a real memory circuit breaker check while building the synonyms map to prevent synonym and synonym_graph token filters from causing OOMs when processing large numbers of synonym rules. By default, the circuit breaker will trip when more than 95% of heap memory is in use.

Behavior on circuit breaker trip is determined by the filter's lenient param value:

• If true, an empty synonyms map is used and the event is logged in the ES logs
• If false, the affected index goes into red state

We need to update the documentation for the synonym and [synonym_graph](https://github.com/elastic/elasticsearch/edit/main/docs/reference/text-analysis/analysis-synonym-graph-tokenfilter.md) token filters to call out this circuit breaker behavior.

Resources

This feature was implemented in elastic/elasticsearch#141669

This feature is tracked by the GH issue elastic/elasticsearch#140564

Which documentation set does this change impact?

Elastic On-Prem and Cloud (all)

Feature differences

The only difference between environments is that circuit breaker limits are not configurable in serverless. In ECH and on-prem, the real memory circuit breaker limit is configurable via the indices.breaker.total.limit cluster setting.

What release is this request related to?

9.4

Serverless release

The week of February 16, 2026

Collaboration model

The documentation team

Point of contact.

Main contact: @Mikep86

Stakeholders: @Mikep86 @jimczi @liranabn @dustincoates