# Watcher

class elasticsearch.client.WatcherClient

  To use this client, access `client.watcher` from an `Elasticsearch` client. For example:

      from elasticsearch import Elasticsearch

      # Create the client instance
      client = Elasticsearch(...)
      # Use the watcher client
      client.watcher.<method>(...)

  ack_watch(*, watch_id, action_id=None, error_trace=None, filter_path=None, human=None, pretty=None)

    Acknowledge a watch.

    Acknowledging a watch enables you to manually throttle the execution of the watch's actions.

    The acknowledgement state of an action is stored in the `status.actions.<id>.ack.state` structure.

    IMPORTANT: If the specified watch is currently being executed, this API will return an error The reason for this behavior is to prevent overwriting the watch status from a watch execution.

    Acknowledging an action throttles further executions of that action until its `ack.state` is reset to `awaits_successful_execution`. This happens when the condition of the watch is not met (the condition evaluates to false). To demonstrate how throttling works in practice and how it can be configured for individual actions within a watch, refer to External documentation.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-ack-watch

    Parameters:

      - watch_id (str) – The watch identifier.

      - action_id (str | Sequence[str] | None) – A comma-separated list of the action identifiers to acknowledge. If you omit this parameter, all of the actions of the watch are acknowledged.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  activate_watch(*, watch_id, error_trace=None, filter_path=None, human=None, pretty=None)

    Activate a watch.

    A watch can be either active or inactive.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-activate-watch

    Parameters:

      - watch_id (str) – The watch identifier.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  deactivate_watch(*, watch_id, error_trace=None, filter_path=None, human=None, pretty=None)

    Deactivate a watch.

    A watch can be either active or inactive.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-deactivate-watch

    Parameters:

      - watch_id (str) – The watch identifier.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  delete_watch(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

    Delete a watch.

    When the watch is removed, the document representing the watch in the `.watches` index is gone and it will never be run again.

    Deleting a watch does not delete any watch execution records related to this watch from the watch history.

    IMPORTANT: Deleting a watch must be done by using only this API. Do not delete the watch directly from the `.watches` index using the Elasticsearch delete document API When Elasticsearch security features are enabled, make sure no write privileges are granted to anyone for the `.watches` index.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-delete-watch

    Parameters:

      - id (str) – The watch identifier.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  execute_watch(*, id=None, action_modes=None, alternative_input=None, debug=None, error_trace=None, filter_path=None, human=None, ignore_condition=None, pretty=None, record_execution=None, simulated_actions=None, trigger_data=None, watch=None, body=None)

    Run a watch.

    This API can be used to force execution of the watch outside of its triggering logic or to simulate the watch execution for debugging purposes.

    For testing and debugging purposes, you also have fine-grained control on how the watch runs. You can run the watch without running all of its actions or alternatively by simulating them. You can also force execution by ignoring the watch condition and control whether a watch record would be written to the watch history after it runs.

    You can use the run watch API to run watches that are not yet registered by specifying the watch definition inline. This serves as great tool for testing and debugging your watches prior to adding them to Watcher.

    When Elasticsearch security features are enabled on your cluster, watches are run with the privileges of the user that stored the watches. If your user is allowed to read index `a`, but not index `b`, then the exact same set of rules will apply during execution of a watch.

    When using the run watch API, the authorization data of the user that called the API will be used as a base, instead of the information who stored the watch. Refer to the external documentation for examples of watch execution requests, including existing, customized, and inline watches.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-execute-watch

    Parameters:

      - id (str | None) – The watch identifier.

      - action_modes (Mapping[str, str | Literal['execute', 'force_execute', 'force_simulate', 'simulate', 'skip']] | None) – Determines how to handle the watch actions as part of the watch execution.

      - alternative_input (Mapping[str, Any] | None) – When present, the watch uses this object as a payload instead of executing its own input.

      - debug (bool | None) – Defines whether the watch runs in debug mode.

      - ignore_condition (bool | None) – When set to true, the watch execution uses the always condition. This can also be specified as an HTTP parameter.

      - record_execution (bool | None) – When set to true, the watch record representing the watch execution result is persisted to the .watcher-history index for the current time. In addition, the status of the watch is updated, possibly throttling subsequent runs. This can also be specified as an HTTP parameter.

      - simulated_actions (Mapping[str, Any] | None)

      - trigger_data (Mapping[str, Any] | None) – This structure is parsed as the data of the trigger event that will be used during the watch execution.

      - watch (Mapping[str, Any] | None) – When present, this watch is used instead of the one specified in the request. This watch is not persisted to the index and record_execution cannot be set.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]

  get_settings(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)

    Get Watcher index settings.

    Get settings for the Watcher internal index (`.watches`). Only a subset of settings are shown, for example `index.auto_expand_replicas` and `index.number_of_replicas`.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-get-settings

    Parameters:

      - master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  get_watch(*, id, error_trace=None, filter_path=None, human=None, pretty=None)

    Get a watch.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-get-watch

    Parameters:

      - id (str) – The watch identifier.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  put_watch(*, id, actions=None, active=None, condition=None, error_trace=None, filter_path=None, human=None, if_primary_term=None, if_seq_no=None, input=None, metadata=None, pretty=None, throttle_period=None, throttle_period_in_millis=None, transform=None, trigger=None, version=None, body=None)

    Create or update a watch.

    When a watch is registered, a new document that represents the watch is added to the `.watches` index and its trigger is immediately registered with the relevant trigger engine. Typically for the `schedule` trigger, the scheduler is the trigger engine.

    IMPORTANT: You must use Kibana or this API to create a watch. Do not add a watch directly to the `.watches` index by using the Elasticsearch index API. If Elasticsearch security features are enabled, do not give users write privileges on the `.watches` index.

    When you add a watch you can also define its initial active state by setting the active parameter.

    When Elasticsearch security features are enabled, your watch can index or search only on indices for which the user that stored the watch has privileges. If the user is able to read index `a`, but not index `b`, the same will apply when the watch runs.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-put-watch

    Parameters:

      - id (str) – The identifier for the watch.

      - actions (Mapping[str, Mapping[str, Any]] | None) – The list of actions that will be run if the condition matches.

      - active (bool | None) – The initial state of the watch. The default value is true, which means the watch is active by default.

      - condition (Mapping[str, Any] | None) – The condition that defines if the actions should be run.

      - if_primary_term (int | None) – Only update the watch if the last operation that has changed the watch has the specified primary term

      - if_seq_no (int | None) – Only update the watch if the last operation that has changed the watch has the specified sequence number

      - input (Mapping[str, Any] | None) – The input that defines the input that loads the data for the watch.

      - metadata (Mapping[str, Any] | None) – Metadata JSON that will be copied into the history entries.

      - throttle_period (str | Literal[-1] | ~typing.Literal[0] | None) – The minimum time between actions being run. The default is 5 seconds. This default can be changed in the config file with the setting xpack.watcher.throttle.period.default_period. If both this value and the throttle_period_in_millis parameter are specified, Watcher uses the last parameter included in the request.

      - throttle_period_in_millis (Any | None) – Minimum time in milliseconds between actions being run. Defaults to 5000. If both this value and the throttle_period parameter are specified, Watcher uses the last parameter included in the request.

      - transform (Mapping[str, Any] | None) – The transform that processes the watch payload to prepare it for the watch actions.

      - trigger (Mapping[str, Any] | None) – The trigger that defines when the watch should run.

      - version (int | None) – Explicit version number for concurrency control

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]

  query_watches(*, error_trace=None, filter_path=None, from_=None, human=None, pretty=None, query=None, search_after=None, size=None, sort=None, body=None)

    Query watches.

    Get all registered watches in a paginated manner and optionally filter watches by a query.

    Note that only the `_id` and `metadata.*` fields are queryable or sortable.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-query-watches

    Parameters:

      - from – The offset from the first result to fetch. It must be non-negative.

      - query (Mapping[str, Any] | None) – A query that filters the watches to be returned.

      - search_after (Sequence[None | bool | float | int | str] | None) – Retrieve the next page of hits using a set of sort values from the previous page.

      - size (int | None) – The number of hits to return. It must be non-negative.

      - sort (Sequence[str | Mapping[str, Any]] | str | Mapping[str, Any] | None) – One or more fields used to sort the search results.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - from_ (int | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]

  start(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)

    Start the watch service.

    Start the Watcher service if it is not already running.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-start

    Parameters:

      - master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – Period to wait for a connection to the master node.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  stats(*, metric=None, emit_stacktraces=None, error_trace=None, filter_path=None, human=None, pretty=None)

    Get Watcher statistics.

    This API always returns basic metrics. You retrieve more metrics by using the metric parameter.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-stats

    Parameters:

      - metric (Sequence[str | Literal['_all', 'current_watches', 'pending_watches', 'queued_watches']] | str | ~typing.Literal['_all', 'current_watches', 'pending_watches', 'queued_watches'] | None) – Defines which additional metrics are included in the response.

      - emit_stacktraces (bool | None) – Defines whether stack traces are generated for each watch that is running.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  stop(*, error_trace=None, filter_path=None, human=None, master_timeout=None, pretty=None)

    Stop the watch service.

    Stop the Watcher service if it is running.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-stop

    Parameters:

      - master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for the master node. If the master node is not available before the timeout expires, the request fails and returns an error. To indicate that the request should never timeout, set it to -1.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

    Return type:

      ObjectApiResponse[Any]

  update_settings(*, error_trace=None, filter_path=None, human=None, index_auto_expand_replicas=None, index_number_of_replicas=None, master_timeout=None, pretty=None, timeout=None, body=None)

    Update Watcher index settings.

    Update settings for the Watcher internal index (`.watches`). Only a subset of settings can be modified. This includes `index.auto_expand_replicas`, `index.number_of_replicas`, `index.routing.allocation.exclude.*`, `index.routing.allocation.include.*` and `index.routing.allocation.require.*`. Modification of `index.routing.allocation.include._tier_preference` is an exception and is not allowed as the Watcher shards must always be in the `data_content` tier.

    https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-watcher-update-settings

    Parameters:

      - index_auto_expand_replicas (str | None)

      - index_number_of_replicas (int | None)

      - master_timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.

      - timeout (str | Literal[-1] | ~typing.Literal[0] | None) – The period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.

      - error_trace (bool | None)

      - filter_path (str | Sequence[str] | None)

      - human (bool | None)

      - pretty (bool | None)

      - body (Dict[str, Any] | None)

    Return type:

      ObjectApiResponse[Any]