ILM Classes

IndexLifecycle

This is the parent class for IlmPhase and IlmStep.

class es_wait.ilm.IndexLifecycle(client: Elasticsearch, pause: float = 9.0, timeout: float = 7200.0, max_exceptions: int = 10, name: str = '')

Bases: Waiter

ILM Step and Phase Parent Class

Initializes the IndexLifecycle waiter.

‘pause’ will check every 15 seconds by default ‘timeout’ is 10 minutes, 30 seconds, which is a reflection of Elasticsearch’s default ILM polling interval of 10 minutes.

add_exception(value: Exception) → None

This method appends value the exceptions list.

Parameters:

value (Exception) – An exception to add

announce() → None

This method is called when the Waiter class is initialized. It logs a level 1 debug message using waitstr.

check() → bool

This will be redefined by each child class

Getter:

Returns if the check was complete

Type:

bool

client

An Elasticsearch client instance

do_health_report

Only changes to True in certain circumstances

property exception_count_msg: str

This property returns a messgage showing the current number of exceptions raised and the maximum number of exceptions allowed.

Getter:

Returns ‘X exceptions raised out of Y allowed’

Type:

str

property exceptions: list

This property returns a list of exceptions raised during the wait.

Getter:

Returns a list of exceptions raised

Type:

list

exceptions_raised

The number of exceptions raised

property explain: str

Getter:

Returns the current ilm explain data for the index

Type:

str

get_explain_data() → Dict | None

This method calls ilm.explain_lifecycle() with name and returns the resulting response.

max_exceptions

The maximum number of exceptions to allow

name

The index name

pause

The delay between checks for completion

property phase_complete: bool

Getter:

Returns True if both action and step for the phase are complete

Type:

bool

timeout

The number of seconds before giving up. -1 means no timeout.

too_many_exceptions() → None

If the number of exceptions raised is greater than or equal to the maximum number of exceptions allowed, then a ExceptionCount will be raised.

wait(frequency: int = 5) → None

This method is where the actual waiting occurs. Depending on what frequency is set to, you should see non-DEBUG level logs no more than every frequency seconds.

If timeout has been reached without check() returning as True, then a TimeoutError will be raised.

If check() returns False, then the method will wait pause seconds before calling check() again.

Elapsed time will be logged every frequency seconds, when check() is True, or when timeout is reached.

If do_health_report is True, then call client.health_report() and pass the results to utils.health_report().

Parameters:

frequency – The number of seconds between log reports on progress.

IlmPhase

class es_wait.ilm.IlmPhase(client: Elasticsearch, pause: float = 9.0, timeout: float = 7200.0, max_exceptions: int = 10, name: str = '', phase: str = '')

Bases: IndexLifecycle

ILM Phase class (child of class IndexLifecycle)

It should be noted that the default ILM polling interval in Elasticsearch is 10 minutes. Setting pause and timeout accordingly is a good idea.

Initializes the IndexLifecycle waiter.

‘pause’ will check every 15 seconds by default ‘timeout’ is 10 minutes, 30 seconds, which is a reflection of Elasticsearch’s default ILM polling interval of 10 minutes.

add_exception(value: Exception) → None

This method appends value the exceptions list.

Parameters:

value (Exception) – An exception to add

announce() → None

This method is called when the Waiter class is initialized. It logs a level 1 debug message using waitstr.

check(max_stuck_count: int = 3) → bool

Check the ILM phase transition

Collect ILM explain data from get_explain_data(), and check for ILM phase change completion. It will return True if the expected phase and the actually collected phase match. If phase is new, it will return True if the collected phase is new or higher (hot, warm, cold, frozen, delete).

Upstream callers need to try/catch any of KeyError (index name changed), NotFoundError, and IlmWaitError.

We cannot not be responsible for retrying with a changed name as it’s not in our scope as a “waiter”

Parameters:

max_stuck_count (int) – The maximum number of times the phase can be stuck before returning raising an exception. Default is 3.

Returns:

Returns if the check was complete

Return type:

bool

client

An Elasticsearch client instance

do_health_report

Only changes to True in certain circumstances

property exception_count_msg: str

This property returns a messgage showing the current number of exceptions raised and the maximum number of exceptions allowed.

Getter:

Returns ‘X exceptions raised out of Y allowed’

Type:

str

property exceptions: list

This property returns a list of exceptions raised during the wait.

Getter:

Returns a list of exceptions raised

Type:

list

exceptions_raised

The number of exceptions raised

property explain: str

Getter:

Returns the current ilm explain data for the index

Type:

str

get_explain_data() → Dict | None

This method calls ilm.explain_lifecycle() with name and returns the resulting response.

has_explain() → bool

Check if the explain data is present :returns: boolean of “The explain data is present”

max_exceptions

The maximum number of exceptions to allow

name

The index name

pause

The delay between checks for completion

phase

The target ILM phase

phase_by_name(num: int) → str

Map a phase number to a phase name

phase_by_num(phase: str) → int

Map a phase name to a phase number

property phase_complete: bool

Getter:

Returns True if both action and step for the phase are complete

Type:

bool

property phase_gte: bool

Getter:

Returns True if the current phase meets or exceeds the target phase

Type:

bool

property phase_lt: bool

Getter:

Returns True if the current phase is less the target phase

Type:

bool

phase_stuck(max_stuck_count: int = 3) → bool

Check if the phase is stuck :param int max_stuck_count: The maximum number of times the phase can be stuck

before returning raising an exception. Default is 3.

Returns:

boolean of “The phase is stuck”

reached_phase() → bool

Check if the phase is what we expect :returns: boolean of “The phase reached its target”

timeout

The number of seconds before giving up. -1 means no timeout.

too_many_exceptions() → None

If the number of exceptions raised is greater than or equal to the maximum number of exceptions allowed, then a ExceptionCount will be raised.

wait(frequency: int = 5) → None

This method is where the actual waiting occurs. Depending on what frequency is set to, you should see non-DEBUG level logs no more than every frequency seconds.

If timeout has been reached without check() returning as True, then a TimeoutError will be raised.

If check() returns False, then the method will wait pause seconds before calling check() again.

Elapsed time will be logged every frequency seconds, when check() is True, or when timeout is reached.

If do_health_report is True, then call client.health_report() and pass the results to utils.health_report().

Parameters:

frequency – The number of seconds between log reports on progress.

IlmStep

class es_wait.ilm.IlmStep(client: Elasticsearch, pause: float = 9.0, timeout: float = 7200.0, max_exceptions: int = 10, name: str = '')

Bases: IndexLifecycle

ILM Step class (child of class IndexLifecycle)

It should be noted that the default ILM polling interval in Elasticsearch is 10 minutes. Setting pause and timeout accordingly is a good idea.

Initializes the IndexLifecycle waiter.

‘pause’ will check every 15 seconds by default ‘timeout’ is 10 minutes, 30 seconds, which is a reflection of Elasticsearch’s default ILM polling interval of 10 minutes.

add_exception(value: Exception) → None

This method appends value the exceptions list.

Parameters:

value (Exception) – An exception to add

announce() → None

This method is called when the Waiter class is initialized. It logs a level 1 debug message using waitstr.

check() → bool

Collect ILM explain data from get_explain_data(), and check for ILM step completion. It will return True if the step and action values are both complete

Upstream callers need to try/catch any of KeyError (index name changed), NotFoundError, and IlmWaitError.

We cannot not be responsible for retrying with a changed name as it’s not in our scope as a “waiter”

Getter:

Returns if the check was complete

Type:

bool

client

An Elasticsearch client instance

do_health_report

Only changes to True in certain circumstances

property exception_count_msg: str

This property returns a messgage showing the current number of exceptions raised and the maximum number of exceptions allowed.

Getter:

Returns ‘X exceptions raised out of Y allowed’

Type:

str

property exceptions: list

This property returns a list of exceptions raised during the wait.

Getter:

Returns a list of exceptions raised

Type:

list

exceptions_raised

The number of exceptions raised

property explain: str

Getter:

Returns the current ilm explain data for the index

Type:

str

get_explain_data() → Dict | None

This method calls ilm.explain_lifecycle() with name and returns the resulting response.

max_exceptions

The maximum number of exceptions to allow

name

The index name

pause

The delay between checks for completion

property phase_complete: bool

Getter:

Returns True if both action and step for the phase are complete

Type:

bool

timeout

The number of seconds before giving up. -1 means no timeout.

too_many_exceptions() → None

If the number of exceptions raised is greater than or equal to the maximum number of exceptions allowed, then a ExceptionCount will be raised.

wait(frequency: int = 5) → None

This method is where the actual waiting occurs. Depending on what frequency is set to, you should see non-DEBUG level logs no more than every frequency seconds.

If timeout has been reached without check() returning as True, then a TimeoutError will be raised.

If check() returns False, then the method will wait pause seconds before calling check() again.

Elapsed time will be logged every frequency seconds, when check() is True, or when timeout is reached.

If do_health_report is True, then call client.health_report() and pass the results to utils.health_report().

Parameters:

frequency – The number of seconds between log reports on progress.