This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Example watches Watcher limitations »
Elastic Docs ›Elasticsearch Guide [8.16] ›Watcher ›Example watches

Watching the status of an Elasticsearch cluster

edit

Watching the status of an Elasticsearch cluster

edit

You can easily configure a basic watch to monitor the health of your Elasticsearch cluster:

Schedule the watch and add an input

edit

A watch schedule controls how often a watch is triggered. The watch input gets the data that you want to evaluate.

The simplest way to define a schedule is to specify an interval. For example, the following schedule runs every 10 seconds:

resp = client.watcher.put_watch(
    id="cluster_health_watch",
    trigger={
        "schedule": {
            "interval": "10s"
        }
    },
)
print(resp)
const response = await client.watcher.putWatch({
  id: "cluster_health_watch",
  trigger: {
    schedule: {
      interval: "10s",
    },
  },
});
console.log(response);
PUT _watcher/watch/cluster_health_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" } 
  }
}

Schedules are typically configured to run less frequently. This example sets the interval to 10 seconds to you can easily see the watches being triggered. Since this watch runs so frequently, don’t forget to delete the watch when you’re done experimenting.

To get the status of your cluster, you can call the cluster health API:

resp = client.cluster.health(
    pretty=True,
)
print(resp)
response = client.cluster.health(
  pretty: true
)
puts response
const response = await client.cluster.health({
  pretty: "true",
});
console.log(response);
GET _cluster/health?pretty

To load the health status into your watch, you simply add an HTTP input that calls the cluster health API:

resp = client.watcher.put_watch(
    id="cluster_health_watch",
    trigger={
        "schedule": {
            "interval": "10s"
        }
    },
    input={
        "http": {
            "request": {
                "host": "localhost",
                "port": 9200,
                "path": "/_cluster/health"
            }
        }
    },
)
print(resp)
const response = await client.watcher.putWatch({
  id: "cluster_health_watch",
  trigger: {
    schedule: {
      interval: "10s",
    },
  },
  input: {
    http: {
      request: {
        host: "localhost",
        port: 9200,
        path: "/_cluster/health",
      },
    },
  },
});
console.log(response);
PUT _watcher/watch/cluster_health_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" }
  },
  "input" : {
    "http" : {
      "request" : {
        "host" : "localhost",
        "port" : 9200,
        "path" : "/_cluster/health"
      }
    }
  }
}

If you’re using Security, then you’ll also need to supply some authentication credentials as part of the watch configuration:

resp = client.watcher.put_watch(
    id="cluster_health_watch",
    trigger={
        "schedule": {
            "interval": "10s"
        }
    },
    input={
        "http": {
            "request": {
                "host": "localhost",
                "port": 9200,
                "path": "/_cluster/health",
                "auth": {
                    "basic": {
                        "username": "elastic",
                        "password": "x-pack-test-password"
                    }
                }
            }
        }
    },
)
print(resp)
const response = await client.watcher.putWatch({
  id: "cluster_health_watch",
  trigger: {
    schedule: {
      interval: "10s",
    },
  },
  input: {
    http: {
      request: {
        host: "localhost",
        port: 9200,
        path: "/_cluster/health",
        auth: {
          basic: {
            username: "elastic",
            password: "x-pack-test-password",
          },
        },
      },
    },
  },
});
console.log(response);
PUT _watcher/watch/cluster_health_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" }
  },
  "input" : {
    "http" : {
      "request" : {
        "host" : "localhost",
        "port" : 9200,
        "path" : "/_cluster/health",
        "auth": {
          "basic": {
            "username": "elastic",
            "password": "x-pack-test-password"
          }
        }
      }
    }
  }
}

It would be a good idea to create a user with the minimum privileges required for use with such a watch configuration.

Depending on how your cluster is configured, there may be additional settings required before the watch can access your cluster such as keystores, truststores, or certificates. For more information, see Watcher settings.

If you check the watch history, you’ll see that the cluster status is recorded as part of the watch_record each time the watch executes.

For example, the following request retrieves the last ten watch records from the watch history:

resp = client.search(
    index=".watcher-history*",
    sort=[
        {
            "result.execution_time": "desc"
        }
    ],
)
print(resp)
response = client.search(
  index: '.watcher-history*',
  body: {
    sort: [
      {
        'result.execution_time' => 'desc'
      }
    ]
  }
)
puts response
const response = await client.search({
  index: ".watcher-history*",
  sort: [
    {
      "result.execution_time": "desc",
    },
  ],
});
console.log(response);
GET .watcher-history*/_search
{
  "sort" : [
    { "result.execution_time" : "desc" }
  ]
}

Add a condition

edit

A condition evaluates the data you’ve loaded into the watch and determines if any action is required. Since you’ve defined an input that loads the cluster status into the watch, you can define a condition that checks that status.

For example, you could add a condition to check to see if the status is RED.

resp = client.watcher.put_watch(
    id="cluster_health_watch",
    trigger={
        "schedule": {
            "interval": "10s"
        }
    },
    input={
        "http": {
            "request": {
                "host": "localhost",
                "port": 9200,
                "path": "/_cluster/health"
            }
        }
    },
    condition={
        "compare": {
            "ctx.payload.status": {
                "eq": "red"
            }
        }
    },
)
print(resp)
const response = await client.watcher.putWatch({
  id: "cluster_health_watch",
  trigger: {
    schedule: {
      interval: "10s",
    },
  },
  input: {
    http: {
      request: {
        host: "localhost",
        port: 9200,
        path: "/_cluster/health",
      },
    },
  },
  condition: {
    compare: {
      "ctx.payload.status": {
        eq: "red",
      },
    },
  },
});
console.log(response);
PUT _watcher/watch/cluster_health_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" } 
  },
  "input" : {
    "http" : {
      "request" : {
       "host" : "localhost",
       "port" : 9200,
       "path" : "/_cluster/health"
      }
    }
  },
  "condition" : {
    "compare" : {
      "ctx.payload.status" : { "eq" : "red" }
    }
  }
}

Schedules are typically configured to run less frequently. This example sets the interval to 10 seconds to you can easily see the watches being triggered.

If you check the watch history, you’ll see that the condition result is recorded as part of the watch_record each time the watch executes.

To check to see if the condition was met, you can run the following query.

resp = client.search(
    index=".watcher-history*",
    pretty=True,
    query={
        "match": {
            "result.condition.met": True
        }
    },
)
print(resp)
response = client.search(
  index: '.watcher-history*',
  pretty: true,
  body: {
    query: {
      match: {
        'result.condition.met' => true
      }
    }
  }
)
puts response
const response = await client.search({
  index: ".watcher-history*",
  pretty: "true",
  query: {
    match: {
      "result.condition.met": true,
    },
  },
});
console.log(response);
GET .watcher-history*/_search?pretty
{
  "query" : {
    "match" : { "result.condition.met" : true }
  }
}

Take action

edit

Recording watch_records in the watch history is nice, but the real power of Watcher is being able to do something in response to an alert. A watch’s actions define what to do when the watch condition is true—​you can send emails, call third-party webhooks, or write documents to an Elasticsearch index or log when the watch condition is met.

For example, you could add an action to index the cluster status information when the status is RED.

resp = client.watcher.put_watch(
    id="cluster_health_watch",
    trigger={
        "schedule": {
            "interval": "10s"
        }
    },
    input={
        "http": {
            "request": {
                "host": "localhost",
                "port": 9200,
                "path": "/_cluster/health"
            }
        }
    },
    condition={
        "compare": {
            "ctx.payload.status": {
                "eq": "red"
            }
        }
    },
    actions={
        "send_email": {
            "email": {
                "to": "username@example.org",
                "subject": "Cluster Status Warning",
                "body": "Cluster status is RED"
            }
        }
    },
)
print(resp)
const response = await client.watcher.putWatch({
  id: "cluster_health_watch",
  trigger: {
    schedule: {
      interval: "10s",
    },
  },
  input: {
    http: {
      request: {
        host: "localhost",
        port: 9200,
        path: "/_cluster/health",
      },
    },
  },
  condition: {
    compare: {
      "ctx.payload.status": {
        eq: "red",
      },
    },
  },
  actions: {
    send_email: {
      email: {
        to: "username@example.org",
        subject: "Cluster Status Warning",
        body: "Cluster status is RED",
      },
    },
  },
});
console.log(response);
PUT _watcher/watch/cluster_health_watch
{
  "trigger" : {
    "schedule" : { "interval" : "10s" }
  },
  "input" : {
    "http" : {
      "request" : {
       "host" : "localhost",
       "port" : 9200,
       "path" : "/_cluster/health"
      }
    }
  },
  "condition" : {
    "compare" : {
      "ctx.payload.status" : { "eq" : "red" }
    }
  },
  "actions" : {
    "send_email" : {
      "email" : {
        "to" : "username@example.org",
        "subject" : "Cluster Status Warning",
        "body" : "Cluster status is RED"
      }
    }
  }
}

For Watcher to send email, you must configure an email account in your elasticsearch.yml configuration file and restart Elasticsearch. To add an email account, set the xpack.notification.email.account property.

For example, the following snippet configures a single Gmail account named work:

xpack.notification.email.account:
  work:
    profile: gmail
    email_defaults:
      from: <email> 
    smtp:
      auth: true
      starttls.enable: true
      host: smtp.gmail.com
      port: 587
      user: <username> 
      password: <password>

Replace <email> with the email address from which you want to send notifications.

Replace <username> with your Gmail user name (typically your Gmail address).

Replace <password> with your Gmail password.

If you have advanced security options enabled for your email account, you need to take additional steps to send email from Watcher. For more information, see Configuring email accounts.

You can check the watch history or the status_index to see that the action was performed.

resp = client.search(
    index=".watcher-history*",
    pretty=True,
    query={
        "match": {
            "result.condition.met": True
        }
    },
)
print(resp)
response = client.search(
  index: '.watcher-history*',
  pretty: true,
  body: {
    query: {
      match: {
        'result.condition.met' => true
      }
    }
  }
)
puts response
const response = await client.search({
  index: ".watcher-history*",
  pretty: "true",
  query: {
    match: {
      "result.condition.met": true,
    },
  },
});
console.log(response);
GET .watcher-history*/_search?pretty
{
  "query" : {
    "match" : { "result.condition.met" : true }
  }
}

Delete the watch

edit

Since the cluster_health_watch is configured to run every 10 seconds, make sure you delete it when you’re done experimenting. Otherwise, you’ll spam yourself indefinitely.

To remove the watch, use the delete watch API:

resp = client.watcher.delete_watch(
    id="cluster_health_watch",
)
print(resp)
response = client.watcher.delete_watch(
  id: 'cluster_health_watch'
)
puts response
const response = await client.watcher.deleteWatch({
  id: "cluster_health_watch",
});
console.log(response);
DELETE _watcher/watch/cluster_health_watch
« Example watches Watcher limitations »