Configuring Elasticsearch as an event source

Elasticsearch is a distributed, RESTful search and analytics engine that stores data as part of the Elastic Stack. You can set up an integration with Elasticsearch to send log information to Netcool® Operations Insight® as events.

Before you begin

The Elasticsearch event source is only supported when event management is deployed in an IBM Cloud® Private environment.

Ensure you have the X-Pack extension for the Elastic Stack installed as described in https://www.elastic.co/guide/en/x-pack/current/installing-xpack.html.

The following event types are supported for this integration:
  • X-Pack Alerting

About this task

Using the X-Pack Alerting (via Watcher) feature, you configure watches to send event information to event management. For information about X-Pack Alerting via Watcher, see https://www.elastic.co/guide/en/x-pack/current/how-watcher-works.html.

Procedure

  1. Click Administration > Integrations with other systems.
  2. Click New integration.
  3. Go to the Elasticsearch tile and click Configure.
  4. Enter a name for the integration and click Copy Copy to add the generated webhook URL to the clipboard. Ensure you save the generated webhook to make it available later in the configuration process. For example, you can save it to a file.
  5. Click Save.
  6. Configure the X-Pack watcher feature in Elasticsearch to forward events to event management. For example, to configure the watcher using the Kibana UI:
    1. Log in to the Kibana UI and to access the Watcher UI as described in https://www.elastic.co/guide/en/kibana/7.4/watcher-ui.html#watcher-getting-started.

      If you are using IBM Cloud Private, you can configure the included Elasticsearch engine to send events to event management. You can open the Kibana UI from the navigation menu in IBM Cloud Private by clicking Network Access > Services > Kibana, or by clicking Platform > Logging.

      Note: Ensure you have Kibana installed in IBM Cloud Private as described in https://www.ibm.com/docs/en/SSBS6K_2.1.0.3/featured_applications/kibana_service.html.
    2. Create a new advanced watch as described in https://www.elastic.co/guide/en/kibana/7.4/watcher-ui.html#watcher-create-advanced-watch. Update the fields as follows:
      The following is an example watch definition for IBM Cloud Private environments where the watch is triggered every 5 minutes to load the Logstash logs that were written in the last 5 minutes and contain any of the following keywords: failed, error, or warning. The watcher posts the payload for such logs to event management using the webhook URL.
      {
        "trigger": {
          "schedule": {
            "interval": "5m"
          }
        },
        "input": {
          "search": {
            "request": {
              "indices": [
                "logstash-2018*"
              ],
              "body": {
                "query": {
                  "bool": {
                    "must_not": {
                      "match": {
                        "kubernetes.container_name": "custom-metrics-adapter"
                      }
                    },
                    "filter": [
                      {
                        "range": {
                          "@timestamp": {
                            "gte": "now-5m"
                          }
                        }
                      },
                      {
                        "terms": {
                          "log": [
                            "failed",
                            "error",
                            "warning"
                          ]
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "actions": {
          "my_webhook": {
            "webhook": {
              "method": "POST",
              "headers": {
                "Content-Type": "application/json"
              },
              "url": "<CEM WEBHOOK>",
              "body": "{{#toJson}}ctx.payload{{/toJson}}"
            }
          }
        }
      }
      Important: Ensure you set the trigger for the watch to a frequency that suits your requirements for monitoring the logs. Consider the load on the system when setting frequency. In the previous example, the watch is triggered every 5 minutes to load the logs that were written in the last 5 minutes using the "schedule": {"interval": "5m"} and "@timestamp": {"gte": "now-5m" } settings. If you set interval to less than 5 minutes in this case, then the same logs are sent to event management more than once, repeating event data in the correlated incidents.
      Restriction: The "terms": {"log": []} section in the watch definition determines the mapping to the event severity levels in event management. The default values are "failed", "error", and "warning", and are mapped to "critical", "major", and "minor" severity levels. If you use any other value, the event severity is mapped to "indeterminate" in event management.
      Attention: In IBM Cloud Private environments ensure you exclude "kubernetes.container_name": "custom-metrics-adapter" from your watch definition using the following setting:
      "must_not": {
                      "match": {
                        "kubernetes.container_name": "custom-metrics-adapter"
                      }
      The size of the custom-metric-adapter logs can be large and overload the event management processing. In addition, the log format is unreadable to users.
    3. Save the watch.
  7. If you are using IBM Cloud Private, ensure the X-Pack watcher feature is enabled; for example:
    1. Load the ELK (Elasticsearch, Logstash, Kibana) stack configmap into a file using the following command:

      kubectl get configmaps logging-elk-elasticsearch-config --namespace=kube-system -o yaml > elasticsearch-config.yaml

    2. Edit the elasticsearch-config.yaml file to enable the watcher: xpack.watcher.enabled: true
    3. Save the file, and replace the configmap using the following command:

      kubectl --namespace kube-system replace -f elasticsearch-config.yaml

    4. Restart Elasticsearch and Kibana.
  8. To start receiving log information as events from Elasticsearch, verify that Enable event management from this source is set to On..