Autoscaling API

The Autoscaling API is used to manage autoscaling policies, preferences, triggers, listeners and to get diagnostics on the state of the cluster.

Read API

The autoscaling Read API is available at /solr/admin/autoscaling or /api/cluster/autoscaling (v2 API style). It returns information about the configured cluster preferences, cluster policy, collection-specific policies triggers and listeners.

This API does not take any parameters.

Read API Response

The output will contain cluster preferences, cluster policy and collection specific policies.

Examples using Read API

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 2
    },
    "cluster-policy": [
        {
            "replica": "<2",
            "shard": "#EACH",
            "node": "#ANY"
        }
    ],
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

Diagnostics API

The diagnostics API shows the violations, if any, of all conditions in the cluster and, if applicable, the collection-specific policy. It is available at the /admin/autoscaling/diagnostics path.

This API does not take any parameters.

Diagnostics API Response

The output will contain sortedNodes which is a list of nodes in the cluster sorted according to overall load in descending order (as determined by the preferences) and violations which is a list of nodes along with the conditions that they violate.

Examples Using Diagnostics API

Here is an example with no violations but in the sortedNodes section, we can see that the first node is most loaded (according to number of cores):

{
    "responseHeader": {
        "status": 0,
        "QTime": 65
    },
    "diagnostics": {
        "sortedNodes": [
            {
                "node": "127.0.0.1:8983_solr",
                "cores": 3
            },
            {
                "node": "127.0.0.1:7574_solr",
                "cores": 2
            }
        ],
        "violations": []
    },
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

Suppose we added a condition to the cluster policy as follows:

{"replica": "<2", "shard": "#EACH", "node": "#ANY"}

However, since the first node in the first example had more than 1 replica for a shard already, then the diagnostics API will return:

{
    "responseHeader": {
        "status": 0,
        "QTime": 45
    },
    "diagnostics": {
        "sortedNodes": [
            {
                "node": "127.0.0.1:8983_solr",
                "cores": 3
            },
            {
                "node": "127.0.0.1:7574_solr",
                "cores": 2
            }
        ],
        "violations": [
            {
                "collection": "gettingstarted",
                "shard": "shard1",
                "node": "127.0.0.1:8983_solr",
                "tagKey": "127.0.0.1:8983_solr",
                "violation": {
                    "replica": "2",
                    "delta": 0
                },
                "clause": {
                    "replica": "<2",
                    "shard": "#EACH",
                    "node": "#ANY",
                    "collection": "gettingstarted"
                }
            }
        ]
    },
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

In the above example the node with port 8983 has two replicas for shard1 in violation of our policy.

Suggestions API

Suggestions are operations recommended by the system according to the policies and preferences the user has set.

Suggestions are made only if there are violations to active policies. The operation section of the response uses the defined preferences to identify the target node.

The API is available at /admin/autocaling/suggestion. Here is an example output from a suggestion request:

{
  "responseHeader":{
    "status":0,
    "QTime":101},
  "suggestions":[{
      "type":"violation",
      "violation":{
        "collection":"mycoll",
        "shard":"shard2",
        "tagKey":"7574",
        "violation":{ "delta":-1},
        "clause":{
          "replica":"0",
          "shard":"#EACH",
          "port":7574,
          "collection":"mycoll"}},
      "operation":{
        "method":"POST",
        "path":"/c/mycoll",
        "command":{"move-replica":{
            "targetNode":"192.168.43.37:8983_solr",
            "replica":"core_node7"}}}},
    {
      "type":"violation",
      "violation":{
        "collection":"mycoll",
        "shard":"shard2",
        "tagKey":"7574",
        "violation":{ "delta":-1},
        "clause":{
          "replica":"0",
          "shard":"#EACH",
          "port":7574,
          "collection":"mycoll"}},
      "operation":{
        "method":"POST",
        "path":"/c/mycoll",
        "command":{"move-replica":{
            "targetNode":"192.168.43.37:7575_solr",
            "replica":"core_node15"}}}}],
  "WARNING":"This response format is experimental.  It is likely to change in the future."}

The suggested operation is an API call that can be invoked to remedy the current violation.

History API

The history of autoscaling events is available at /admin/autoscaling/history. It returns information about past autoscaling events and details about their processing. This history is kept in the .system collection, and is populated by a trigger listener SystemLogListener. By default this listener is added to all new triggers.

History events are regular Solr documents so they can be also accessed directly by searching on the .system collection. The history handler acts as a regular search handler, so all query parameters supported by /select handler for that collection are supported here too. However, the history handler makes this process easier by offering a simpler syntax and knowledge of field names used by SystemLogListener for serialization of event data.

History documents contain the action context, if it was available, which gives further insight into e.g., exact operations that were computed and/or executed.

Specifically, the following query parameters can be used (they are turned into filter queries, so an implicit AND is applied):

trigger

The name of the trigger.

eventType

The event type or trigger type (e.g., nodeAdded).

collection

The name of the collection involved in event processing.

stage

An event processing stage.

action

A trigger action.

node

A node name that the event refers to.

beforeAction

A beforeAction stage.

afterAction

An afterAction stage.

Example output
{
    "responseHeader": {
        "status": 0,
        "QTime": 64
    },
    "response": {
        "numFound": 2,
        "start": 0,
        "docs": [
            {
                "type": "autoscaling_event",
                "source_s": "SystemLogListener",
                "id": "15f53efdf4bT2qlmj80580yuu997vktddfob3",
                "event.id_s": "14f0d67fe7b97d80T2qlmj80580yuu997vktddfob2",
                "event.type_s": "NODELOST",
                "event.source_s": ".auto_add_replicas",
                "event.time_l": 1508941720006000000,
                "timestamp": "2017-10-25T14:29:10.091Z",
                "event.property.eventTimes_ss": [
                    "1508941720006000000"
                ],
                "event.property._enqueue_time__ss": [
                    "1508941750088000000"
                ],
                "event.property.nodeNames_ss": [
                    "192.168.1.104:7574_solr"
                ],
                "stage_s": "STARTED",
                "event_str": "{\n  \"id\":\"14f0d67fe7b97d80T2qlmj80580yuu997vktddfob2\",\n  \"source\":\".auto_add_replicas\",\n  \"eventTime\":1508941720006000000,\n  \"eventType\":\"NODELOST\",\n  \"properties\":{\n    \"eventTimes\":[1508941720006000000],\n    \"_enqueue_time_\":1508941750088000000,\n    \"nodeNames\":[\"192.168.1.104:7574_solr\"]}}",
                "_version_": 1582240104552857600
            },
            {
                "type": "autoscaling_event",
                "source_s": "SystemLogListener",
                "id": "15f53eff316T2qlmj80580yuu997vktddfob6",
                "event.id_s": "14f0d67fe7b97d80T2qlmj80580yuu997vktddfob2",
                "event.type_s": "NODELOST",
                "event.source_s": ".auto_add_replicas",
                "event.time_l": 1508941720006000000,
                "timestamp": "2017-10-25T14:29:15.158Z",
                "event.property.eventTimes_ss": [
                    "1508941720006000000"
                ],
                "event.property._enqueue_time__ss": [
                    "1508941750088000000"
                ],
                "event.property.nodeNames_ss": [
                    "192.168.1.104:7574_solr"
                ],
                "stage_s": "SUCCEEDED",
                "event_str": "{\n  \"id\":\"14f0d67fe7b97d80T2qlmj80580yuu997vktddfob2\",\n  \"source\":\".auto_add_replicas\",\n  \"eventTime\":1508941720006000000,\n  \"eventType\":\"NODELOST\",\n  \"properties\":{\n    \"eventTimes\":[1508941720006000000],\n    \"_enqueue_time_\":1508941750088000000,\n    \"nodeNames\":[\"192.168.1.104:7574_solr\"]}}",
                "_version_": 1582240109859700736
            }
        ]
    }
}
Broken v2 API support

Due to a bug in Solr 7.1.0, the History API is available only at the path /admin/autoscaling/history. Using the /api/cluster/autoscaling/history endpoint returns an error.

Write API

The Write API is available at the same /admin/autoscaling and /api/cluster/autoscaling endpoints as the Read API but can only be used with the POST HTTP verb.

The payload of the POST request is a JSON message with commands to set and remove components. Multiple commands can be specified together in the payload. The commands are executed in the order specified and the changes are atomic, i.e., either all succeed or none.

Create and Modify Cluster Preferences

Cluster preferences are specified as a list of sort preferences. Multiple sorting preferences can be specified and they are applied in the order they are set.

They are defined using the set-cluster-preferences command.

Each preference is a JSON map having the following syntax:

{'<sort_order>':'<sort_param>', 'precision':'<precision_val>'}

See the section Cluster Preferences Specification for details about the allowed values for the sort_order, sort_param and precision parameters.

Changing the cluster preferences after the cluster is already built doesn’t automatically reconfigure the cluster. However, all future cluster management operations will use the changed preferences.

Input

{
"set-cluster-preferences" : [
  {"minimize": "cores"}
  ]
}

Output

The output has a key named result which will return either success or failure depending on whether the command succeeded or failed.

{
    "responseHeader": {
        "status": 0,
        "QTime": 138
    },
    "result": "success",
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

Example Setting Cluster Preferences

In this example we add cluster preferences that sort on three different parameters:

{
  "set-cluster-preferences": [
    {
      "minimize": "cores",
      "precision": 2
    },
    {
      "maximize": "freedisk",
      "precision": 100
    },
    {
      "minimize": "sysLoadAvg",
      "precision": 10
    }
  ]
}

We can remove all cluster preferences by setting preferences to an empty list.

{
  "set-cluster-preferences": []
}

Create and Modify Cluster Policies

Cluster policies are set using the set-cluster-policy command.

Like set-cluster-preferences, the policy definition is a JSON map defining the desired attributes and values.

Refer to the Policy Specification section for details of the allowed values for each condition in the policy.

Input:

{
"set-cluster-policy": [
  {"replica": "<2", "shard": "#EACH", "node": "#ANY"}
  ]
}

Output:

{
    "responseHeader": {
        "status": 0,
        "QTime": 47
    },
    "result": "success",
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

We can remove all cluster policy conditions by setting policy to an empty list.

{
  "set-cluster-policy": []
}

Changing the cluster policy after the cluster is already built doesn’t automatically reconfigure the cluster. However, all future cluster management operations will use the changed cluster policy.

Create and Modify Collection-Specific Policy

The set-policy command accepts a map of policy names to the list of conditions for that policy. Multiple named policies can be specified together. A named policy that does not exist already is created and if the named policy accepts already then it is replaced.

Refer to the Policy Specification section for details of the allowed values for each condition in the policy.

Input

{
"set-policy": {
  "policy1": [
    {"replica": "1", "shard": "#EACH", "port": "8983"}
    ]
  }
}

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 246
    },
    "result": "success",
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

Changing the policy after the collection is already built doesn’t automatically reconfigure the collection. However, all future cluster management operations will use the changed policy.

Remove a Collection-Specific Policy

The remove-policy command accepts a policy name to be removed from Solr. The policy being removed must not be attached to any collection otherwise the command will fail.

Input

{"remove-policy": "policy1"}

Output

{
    "responseHeader": {
        "status": 0,
        "QTime": 42
    },
    "result": "success",
    "WARNING": "This response format is experimental.  It is likely to change in the future."
}

If you attempt to remove a policy that is being used by a collection, this command will fail to delete the policy until the collection itself is deleted.

Create/Update Trigger

The set-trigger command can be used to create a new trigger or overwrite an existing one.

You can see the section Trigger Configuration for a full list of configuration options.

Creating a nodeAdded Trigger
{
 "set-trigger": {
  "name" : "node_added_trigger",
  "event" : "nodeAdded",
  "waitFor" : "1s"
 }
}
Updating Trigger with waitFor set to 5 seconds
{
 "set-trigger": {
  "name" : "node_added_trigger",
  "event" : "nodeAdded",
  "waitFor" : "5s",
 }
}
Creating a nodeLost Trigger
{
 "set-trigger": {
  "name" : "node_lost_trigger1",
  "event" : "nodeLost",
  "waitFor" : "60s",
 }
}

Remove Trigger

The remove-trigger command can be used to remove a trigger. It accepts a single parameter: the name of the trigger.

Removing the nodeLost Trigger
{
 "remove-trigger": {
  "name" : "node_lost_trigger1"
 }
}

Create/Update Trigger Listener

The set-listener command can be used to create or modify a listener for a trigger.

You can see the section Trigger Listener Configuration for a full list of configuration options.

Creating a listener for the nodeAdded Trigger
{
 "set-listener": {
    "name": "foo",
    "trigger": "node_added_trigger",
    "stage": ["STARTED", "ABORTED", "SUCCEEDED", "FAILED"],
    "class": "com.example.Listener"
 }
}

Remove Trigger Listener

The remove-listener command can be used to remove an existing listener. It accepts a single parameter: the name of the listener.

Removing the foo listener
{
 "remove-listener": {
    "name": "foo"
 }
}

Change Autoscaling Properties

The set-properties command can be used to change the default properties used by the Autoscaling framework.

The following properties can be specified in the payload:

triggerScheduleDelaySeconds

This is the delay in seconds between two executions of a trigger. Every trigger is scheduled using Java’s ScheduledThreadPoolExecutor with this delay. The default is 1 second.

triggerCooldownPeriodSeconds

Solr pauses all other triggers for this cool down period after a trigger fires so that the system can stabilize before running triggers again. The default is 5 seconds.

triggerCorePoolSize

The core pool size of the ScheduledThreadPoolExecutor used to schedule triggers. The default is 4 threads.

actionThrottlePeriodSeconds

This is the minimum throttling delay between executing actions for triggers. It is guaranteed that actions for two trigger events are executed after this delay period. The default is 5 seconds.

The command allows setting arbitrary properties in addition to the above properties. Such arbitrary properties can be useful in custom TriggerAction instances.

Change default triggerScheduleDelaySeconds
{
  "set-properties": {
    "triggerScheduleDelaySeconds": 8
  }
}

The set-properties command replaces older values if present. So using set-properties to set the same value twice will overwrite the old value. If a property is not specified then it retains the last set value or the default, if no change was made. A changed value can be unset by using a null value.

Revert changed value of triggerScheduleDelaySeconds to default
{
  "set-properties": {
    "triggerScheduleDelaySeconds": null
  }
}

The changed values of these properties, if any, can be read using the Autoscaling Read API in the properties section.

Comments on this Page

We welcome feedback on Solr documentation. However, we cannot provide application support via comments. If you need help, please send a message to the Solr User mailing list.

©2017 Apache Software Foundation. All rights reserved.
Site Version: 7.2
Site last generated: 2017-12-18

Apache Solr