Search...Watcher(3pm)

📦 version 7.715, in ubuntu jammy

💖 NAME 💖

okay bestie, so Search::Elasticsearch::Client::7_0::Direct::Watcher is the plugin that hands you the whole Watcher API for Search::Elasticsearch 7.x. that's it. that's the whole job. it's giving "alerts but make it perl". 🎀

✨ VERSION ✨

version 7.715 — yes she has a version number and yes she's proud of it. 💅

🌸 SYNOPSIS 🌸

my $response = $es->watcher->start();

that's it. one line. we love a low-effort entrance. 👑

🦋 DESCRIPTION 🦋

so this class extends the Search::Elasticsearch client with a "watcher" namespace, and that namespace is what gives you the Watcher APIs. like, that's the whole vibe:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api.html

extend client → get namespace → get power. iconic. 🌈

💜 METHODS 💜

the full documentation for the Watcher feature lives right here if you want the deep lore:

https://www.elastic.co/guide/en/x-pack/current/xpack-alerting.html

🍓 put_watch()

$response = $es->watcher->put_watch(
    id    => $watch_id,     # required
    body  => {...}
);

put_watch() is your girl for registering a brand new watcher, or for updating one that already exists. either way, she's handling it. 💅

peep the put_watch docs if you want more:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-put-watch.html

query string parameters, bestie — here's the list, all of them, no skips:

  • "active"
  • "error_trace"
  • "human"
  • "if_primary_term"
  • "if_seq_no"
  • "master_timeout"
  • "version"

🧚 get_watch()

$response = $es->watcher->get_watch(
    id    => $watch_id,     # required
);

get_watch() retrieves a watch by its ID. simple, clean, no drama. ✨

the get_watch docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-get-watch.html

query string parameters:

  • "error_trace"
  • "human"

🎀 delete_watch()

$response = $es->watcher->delete_watch(
    id    => $watch_id,     # required
);

delete_watch() deletes a watch by its ID. gone. bye. no cap. 💀

query string parameters:

  • "error_trace"
  • "force"
  • "human"
  • "master_timeout"

and the delete_watch docs, for the receipts:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-delete-watch.html

💖 execute_watch()

$response = $es->watcher->execute_watch(
    id    => $watch_id,     # optional
    body  => {...}          # optional
);

execute_watch() forces a previously registered watch to actually run. yes, like manually poking it. and ngl, the optional params get passed in the body. 🔥

query string parameters:

  • "debug"
  • "error_trace"
  • "human"

execute_watch docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-execute-watch.html

🌈 ack_watch()

$response = $es->watcher->ack_watch(
    watch_id => $watch_id,                  # required
    action_id => $action_id | \@action_ids  # optional
);

ack_watch() is how you manually throttle the execution of a watch. she's the brakes, bestie. 🛑

query string parameters:

  • "error_trace"
  • "human"
  • "master_timeout"

ack_watch docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-ack-watch.html

⭐ activate_watch()

$response = $es->watcher->activate_watch(
    watch_id => $watch_id,                  # required
);

activate_watch() activates a deactive watch. wake her up, she's got main character energy to get back to. 👑

query string parameters:

  • "error_trace"
  • "human"
  • "master_timeout"

activate_watch docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-activate-watch.html

🙈 deactivate_watch()

$response = $es->watcher->deactivate_watch(
    watch_id => $watch_id,                  # required
);

deactivate_watch() deactivates an active watch. nap time. she earned it. 😴

query string parameters:

  • "error_trace"
  • "human"
  • "master_timeout"

deactivate_watch docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-deactivate-watch.html

🫶 stats()

$response = $es->watcher->stats(
    metric => $metric       # optional
);

stats() gives you the tea on the status of the watcher plugin. iykyk. ☕

stats docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stats.html

query string parameters:

  • "error_trace"
  • "human"

💀 stop()

$response = $es->watcher->stop();

stop() stops the watcher service — but only if it's running. if she's already off, she stays off. 🤷

stop docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-stop.html

query string parameters:

  • "error_trace"
  • "human"

✨ start()

$response = $es->watcher->start();

start() starts the watcher service if it's not already running. and if it is already running? she doesn't double-start. respectful. 💅

start docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-start.html

query string parameters:

  • "error_trace"
  • "human"

🦋 restart()

$response = $es->watcher->restart();

restart() stops and then starts the watcher service. the classic glow-up arc: she leaves, she comes back better. periodt. 🌟

restart docs:

https://www.elastic.co/guide/en/elasticsearch/reference/current/watcher-api-restart.html

query string parameters:

  • "error_trace"
  • "human"

🌸 AUTHOR 🌸

Enrico Zimuel <enrico.zimuel@elastic.co> — shoutout to the legend, no cap. 🫶

this software is Copyright (c) 2021 by Elasticsearch BV.

and it's free software, licensed under:

The Apache License, Version 2.0, January 2004

and that's the whole page bestie, you ate it. 🎀 this beauty is running on perl v5.32.1, dated 2021-10-23, and she goes by Search...Watcher(3pm). mwah. 💖✨

📦 where this page comes from