= SolrCloud Autoscaling Listeners
// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

[WARNING]
.Autoscaling is deprecated
====
The autoscaling framework in its current form is deprecated and will be removed in Solr 9.0.

Some features relating to replica placement will be replaced in 9.0, but other features are not likely to be replaced.

There is no planned replacement for listeners.
====

Trigger Listeners allow users to configure additional behavior related to trigger events as they are being processed.

For example, users may want to record autoscaling events to an external system, or notify an administrator when a
particular type of event occurs or when its processing reaches certain stage (e.g., failed).

Listener configuration always refers to a specific trigger configuration because a listener is notified of
events generated by that specific trigger. Several (or none) named listeners can be registered for a trigger,
and they will be notified in the order in which they were defined.

Listener configuration can specify what processing stages are of interest, and when an event enters this processing stage the listener will be notified. Currently the following stages are recognized:

* STARTED - when an event has been generated by a trigger and its processing is starting.
* ABORTED - when event was being processed while the source trigger closed.
* BEFORE_ACTION - when a `TriggerAction` is about to be invoked. Action name and the current `ActionContext` are passed to the listener.
* AFTER_ACTION - after a `TriggerAction` has been successfully invoked. Action name, `ActionContext` and the list of action
  names invoked so far are passed to the listener.
* FAILED - when event processing failed (or when a `TriggerAction` failed)
* SUCCEEDED - when event processing completes successfully

Listener configuration can also specify what particular actions are of interest, both before and/or after they are invoked.

== Listener Configuration
Currently the following listener configuration properties are supported:

`name`::
(string, required) A unique listener configuration name.

`trigger`::
(string, required) The name of an existing trigger configuration.

`class`::
(string, required) A listener implementation class name.

`stage`::
(list of strings, optional, ignored case) A list of processing stages that
 this listener should be notified. Default is empty list.

`beforeAction`::
(list of strings, optional) A list of action names (as defined in trigger configuration) before
which the listener will be notified. Default is empty list.

`afterAction`::
(list of strings, optional) A list of action names after which the listener will be notified.
Default is empty list.

TIP: Additional implementation-specific properties may be provided, depending on the listener implementation.

Note: when both `stage` and `beforeAction` / `afterAction` lists are non-empty then the listener will be notified both
when a specified stage is entered and before / after specified actions.

=== Managing Listener Configurations
Listener configurations are managed using the Autoscaling Write API, and using `set-listener` and `remove-listener`
commands.

For example:

[source,json]
----
{
 "set-listener": {
    "name": "foo",
    "trigger": "node_lost_trigger",
    "stage": ["STARTED", "ABORTED", "SUCCEEDED", "FAILED"],
    "class": "solr.SystemLogListener"
 }
}
----

[source,json]
----
{
 "remove-listener": {
    "name": "foo"
 }
}
----

== Listener Implementations
Trigger listeners must implement the `TriggerListener` interface. Solr provides some
implementations of trigger listeners, which cover common use cases. These implementations are described below, together with their configuration parameters.

=== SystemLogListener
This trigger listener sends trigger events and processing context as documents for indexing in
SolrCloud `.system` collection.

When a trigger configuration is first created, a corresponding trigger listener configuration that
uses `SystemLogListener` is also automatically created, to make sure that all events and
actions related to the autoscaling framework are logged to the `.system` collection.

Supported configuration properties:

`collection`::
(string, optional) Specifies the target collection where documents are sent.
Default value is `.system`. If the target collection is missing the listener will
silently discard events.
+
NOTE: In rare situations when the target collection is in
an unstable state (e.g., when some leader replicas were just lost and the leader election hasn't
finished running yet), the listener may not be able to index some events. In such cases a
WARN message with the details of the event(s) will be added to the regular logs.

`enabled`::
(boolean, optional) Enables the listener when true. Default value is true.

Documents created by this listener have several predefined fields:

* `id` - time-based random id
* `type` - always set to `autoscaling_event`
* `source_s` - always set to `SystemLogListener`
* `timestamp` - current time when document was created
* `stage_s` - current stage of event processing
* `action_s` - current action name, if available
* `message_t` - optional additional message
* `error.message_t` - message from Throwable, if available
* `error.details_t` - stacktrace from Throwable, if available
* `before.actions_ss` - list of action names to be invoked so far
* `after.actions_ss` - list of action names that have been successfully invoked so far
* `event_str` - JSON representation of all event properties
* `context_str` - JSON representation of all `ActionContext` properties, if available

The following fields are created using the information from trigger event:

* `event.id_s` - event id
* `event.type_s` - event type
* `event.source_s` - event source (trigger name)
* `event.time_l` - Unix time when the event was created (may significantly differ from the time when it was actually
processed)
* `event.property.*` - additional fields that represent other arbitrary event properties. These fields use either
`_s` or `_ss` suffix depending on whether the property value is a collection (values inside collection are treated as
strings, there's no recursive flattening)

The following configuration is used for the automatically created listener (in this case for a
trigger named `foo`):

[source,json]
----
{
 "name" : "foo.system",
 "trigger" : "solr.SystemLogListener",
 "stage" : ["STARTED", "ABORTED", "SUCCEEDED", "FAILED", "BEFORE_ACTION", "AFTER_ACTION"]
}
----

=== HttpTriggerListener
This listener uses HTTP POST to send a representation of the event and context to a specified URL.
The URL, payload, and headers may contain property substitution patterns, which are then replaced with values taken from the current event or context properties.

Templates use the same syntax as property substitution in Solr configuration files, e.g.,
`${foo.bar:baz}` means that the value of `foo.bar` property should be taken, and `baz` should be used
if the value is absent.

Supported configuration properties:

`url`::
(string, required) A URL template.

`payload`::
(string, optional) A payload template. If absent, a JSON map of all properties listed above will be used.

`contentType`::
(string, optional) A payload content type. If absent then `application/json` will be used.

`header.*`::
(string, optional) A header template(s). The name of the property without "header." prefix defines the literal header name.

`timeout`::
(int, optional) Connection and socket timeout in milliseconds. Default is `60000` milliseconds (60 seconds).

`followRedirects`::
(boolean, optional) Allows following redirects. Default is `false`.

The following properties are available in context and can be referenced from templates:

* `config.*` - listener configuration properties
* `event.*` - current event properties
* `stage` - current stage of event processing
* `actionName` - optional current action name
* `context.*` - optional ActionContext properties
* `error` - optional error string (from Throwable.toString())
* `message` - optional message

.Example HttpTriggerListener
[source,json]
----
{
 "name": "foo",
 "trigger": "node_added_trigger",
 "class": "solr.HttpTriggerListener",
 "url": "http://foo.com/${config.name:invalidName}/${config.properties.xyz:invalidXyz}/${event.eventType}",
 "xyz": "foobar",
 "header.X-Trigger": "${config.trigger}",
 "payload": "actionName=${actionName}, source=${event.source}, type=${event.eventType}",
 "contentType": "text/plain",
 "stage": ["STARTED", "ABORTED", "SUCCEEDED", "FAILED"],
 "beforeAction": ["compute_plan", "execute_plan"],
 "afterAction": ["compute_plan", "execute_plan"]
}
----

This configuration specifies that each time one of the listed stages is reached, or before and after each of the listed
actions is executed, the listener will send the templated payload to a URL that also depends on the configuration and the current event,
and with a custom header that indicates the trigger name.