Как работает Watcher

Вы добавляете watch, чтобы автоматически выполнять действие, когда выполняются определенные условия. Условия обычно основаны на данных, загруженных в watch, также известные как Watch Payload. Это содержимое может загружаться из разных источников — из Elasticsearch, внешнего HTTP-сервиса или даже из комбинации этих источников.

Например, вы можете настроить watch, чтобы отправлять электронное письмо системному администратору, когда поиск в данных журналов показывает слишком много ошибок 503 за последние 5 минут.

В этом разделе описываются элементы watch и принцип их работы.

Watch состоит из триггера, ввода, условия и действий. Действия определяют, что нужно сделать, когда выполняется условие. Кроме того, вы можете определить условия и преобразования для обработки и подготовки содержимого watch перед выполнением действий.

Например, следующий фрагмент кода показывает запрос создания или обновления watch, который определяет watch, ищущий события ошибок в логах:

PUT _watcher/watch/log_errors
{
  "metadata" : { 
    "color" : "red"
  },
  "trigger" : { 
    "schedule" : {
      "interval" : "5m"
    }
  },
  "input" : { 
    "search" : {
      "request" : {
        "indices" : "log-events",
        "body" : {
          "size" : 0,
          "query" : { "match" : { "status" : "error" } }
        }
      }
    }
  },
  "condition" : { 
    "compare" : { "ctx.payload.hits.total" : { "gt" : 5 }}
  },
  "transform" : { 
    "search" : {
        "request" : {
          "indices" : "log-events",
          "body" : {
            "query" : { "match" : { "status" : "error" } }
          }
        }
    }
  },
  "actions" : { 
    "my_webhook" : {
      "webhook" : {
        "method" : "POST",
        "host" : "mylisteninghost",
        "port" : 9200,
        "path" : "/{{watch_id}}",
        "body" : "Encountered {{ctx.payload.hits.total}} errors"
      }
    },
    "email_administrator" : {
      "email" : {
        "to" : "sys.admino@host.domain",
        "subject" : "Encountered {{ctx.payload.hits.total}} errors",
        "body" : "Too many error in the system, see attached data",
        "attachments" : {
          "attached_data" : {
            "data" : {
              "format" : "json"
            }
          }
        },
        "priority" : "high"
      }
    }
  }
}

При добавлении watch Watcher немедленно регистрирует его триггер с соответствующим движком триггеров. Watches, у которых есть триггер schedule, регистрируются в движке триггеров scheduler.

Планировщик отслеживает время и запускает watch в соответствии с их расписаниями. На каждом узле, содержащем один из .watches фрагментов, запускается планировщик, связанный с жизненным циклом watcher. Хотя все главные и вторичные фрагменты учитываются, при запуске watch watcher также гарантирует, что каждый watch запускается только на одном из этих фрагментов. Чем больше вторичных фрагментов вы добавите, тем более распределенным будет выполнение watch. Если вы добавляете или удаляете вторичные фрагменты, все watch необходимо перезагрузить. Если фрагмент перемещается, первичный и все вторичные фрагменты этого конкретного фрагмента будут перезагружены.

Поскольку watch выполняются на узле, на котором находятся фрагменты watch, вы можете создавать выделенные узлы watcher, используя фильтрацию распределения фрагментов.

Вы можете настроить узлы со свойством node.attr.role: watcher, а затем настроить индекс .watches следующим образом:

PUT .watches/_settings
{
  "index.routing.allocation.include.role": "watcher"
}

Когда служба Watcher остановлена, планировщик останавливается вместе с ней. Движки триггеров используют отдельный пул потоков от того, который используется для выполнения watch.

Когда watch запускается, Watcher помещает его в очередь на выполнение. Создается и добавляется документ watch_record в историю watch, а статус watch устанавливается в awaits_execution.

При запуске выполнения Watcher создает контекст выполнения watch для watch. Контекст выполнения предоставляет скрипты и шаблоны с доступом к метаданным watch, содержимому, идентификатору watch, времени выполнения и информации о триггере. Более подробную информацию см. в разделе Контекст выполнения Watch.

Во время процесса выполнения Watcher:

После завершения выполнения watch результат выполнения записывается как Запись Watch в истории watch. Запись watch включает время выполнения и продолжительность, выполнено ли условие watch и статус каждого выполненного действия.

На следующей диаграмме показан процесс выполнения watch:

Watcher поддерживает как ограничение по времени, так и подтверждение. Это позволяет предотвратить многократное выполнение действий для одного и того же события.

По умолчанию Watcher использует временное ограничение с периодом ограничения 5 секунд. Это означает, что если watch выполняется каждую секунду, его действия выполняются максимум один раз каждые 5 секунд, даже когда условие всегда выполняется. Вы можете настроить период ограничения на основе каждого действия или на уровне watch.

Подтверждение позволяет указать Watcher не отправлять больше уведомлений о watch, пока выполняется его условие. Как только условие оценивается как false, подтверждение очищается, и Watcher продолжает выполнять действия watch в обычном режиме.

Дополнительную информацию см. в разделе Подтверждение и ограничение.

По умолчанию при добавлении watch он сразу же устанавливается в состояние активный, регистрируется в соответствующем движке триггеров и выполняется в соответствии с его настроенным триггером.

Вы также можете установить watch в состояние неактивный. Неактивные watch не регистрируются в движке триггеров и никогда не могут быть запущены.

Чтобы установить watch в неактивное состояние при его создании, установите параметр active в неактивный. Чтобы деактивировать существующий watch, используйте API деактивации watch. Чтобы активировать неактивный watch, используйте API активации watch.

Деактивация watch полезна в различных ситуациях. Например, если у вас есть watch, который отслеживает внешнюю систему, и вам нужно остановить эту систему на время технического обслуживания, вы можете деактивировать watch, чтобы предотвратить ложные сообщения о проблемах доступности во время окна технического обслуживания.

Деактивация watch также позволяет сохранить его для будущего использования, не удаляя его из системы.

При определении watch вы можете использовать скрипты и шаблоны. Скрипты и шаблоны могут ссылаться на элементы в контексте выполнения watch, включая содержимое watch. Контекст выполнения определяет переменные, которые можно использовать в скрипте, и заполнитель параметров в шаблоне.

Watcher использует инфраструктуру скриптов Elasticsearch, которая поддерживает встроенные и хранящиеся шаблоны и скрипты. Скрипты и шаблоны компилируются и кэшируются Elasticsearch для оптимизации периодического выполнения. Также поддерживается автоматическая загрузка. Более подробную информацию см. в разделе Скрипты и Как писать скрипты.

Следующий фрагмент кода показывает основную структуру контекста выполнения watch:

{
  "ctx" : {
    "metadata" : { ... }, 
    "payload" : { ... }, 
    "watch_id" : "<id>", 
    "execution_time" : "20150220T00:00:10Z", 
    "trigger" : { 
      "triggered_time" : "20150220T00:00:10Z",
      "scheduled_time" : "20150220T00:00:00Z"
    },
    "vars" : { ... } 
}

Вы можете использовать скрипты для определения условий и преобразований. По умолчанию язык сценариев — Painless.

Скрипты могут ссылаться на любые значения в контексте выполнения наблюдения или значения, явно переданные через параметры скрипта.

Например, если метаданные наблюдения содержат поле color (например, "metadata" : {"color": "red"}), вы можете получить доступ к его значению через переменную ctx.metadata.color. Если вы передаете параметр color в качестве части определения условия или преобразования (например, "params" : {"color": "red"}), вы можете получить доступ к его значению через переменную color.

Шаблоны используются для определения динамического содержимого наблюдения. Во время выполнения шаблоны извлекают данные из контекста выполнения наблюдения. Например, вы можете использовать шаблон для заполнения поля subject для действия email данными, хранящимися в полезной нагрузке наблюдения. Шаблоны также могут получать доступ к значениям, явно переданным через параметры шаблона.

Вы определяете шаблоны, используя язык сценариев Mustache.

Например, следующий фрагмент демонстрирует, как шаблоны позволяют создавать динамические темы в отправленных письмах:

{
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : "{{ctx.metadata.color}} alert"
      }
    }
  }
}

Чтобы определить встроенный шаблон или скрипт, просто укажите его непосредственно в значении поля. Например, следующий фрагмент настраивает тему действия email с помощью встроенного шаблона, который ссылается на значение color в метаданных контекста.

"actions" : {
  "email_notification" : {
     "email" : {
       "subject" : "{{ctx.metadata.color}} alert"
     }
   }
  }
}

Для скрипта просто укажите встроенный скрипт в качестве значения поля script. Например:

"condition" : {
  "script" : "return true"
}

Вы также можете явно указать тип встроенного элемента, используя формальное определение объекта в качестве значения поля. Например:

"actions" : {
  "email_notification" : {
    "email" : {
      "subject" : {
         "source" : "{{ctx.metadata.color}} alert"
      }
    }
  }
}

Формальное определение объекта для скрипта будет следующим:

"condition" : {
  "script" : {
    "source": "return true"
  }
}

Если вы сохраняете свои шаблоны и скрипты, вы можете ссылаться на них по идентификатору.

Чтобы сослаться на сохраненный скрипт или шаблон, используйте формальное определение объекта и укажите его идентификатор в поле id. Например, следующий фрагмент ссылается на шаблон email_notification_subject:

{
  ...
  "actions" : {
    "email_notification" : {
      "email" : {
        "subject" : {
          "id" : "email_notification_subject",
          "params" : {
            "color" : "red"
          }
        }
      }
    }
  }
}