Skip to content

Latest commit

 

History

History
290 lines (244 loc) · 8.29 KB

elasticsearch-query.md

File metadata and controls

290 lines (244 loc) · 8.29 KB
Raw

elasticsearch-query

Monitor Type: elasticsearch-query (Source)

Accepts Endpoints: Yes

Multiple Instances Allowed: Yes

Overview

This monitor is in beta.

This monitor metricizes aggregated responses from Elasticsearch. The monitor constructs SignalFx datapoints based on Elasticsearch aggregation types and also aggregation names.

An simple configuration looks like the following:

monitors:
- type: elasticsearch-query
 host: localhost
 port: 9200
 index: <name_of_index>
 elasticsearchRequest: |
    {
      "query" : {
        "range" : {
          "@timestamp" : {
            "gte": "now-5m"
          }
        }
      },
      "aggs": {
        "avg_cpu_utilization": {
          "avg": {
            "field": "cpu_utilization"
          }
        }
      }
    }
intervalSeconds: 300

The elasticsearchRequest takes in a string request in the format specified [here] (https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html).

The above query is performed against an index that has documents that take the following form

{
   'cpu_utilization':87,
   'memory_utilization':94,
   'host':'helsniki',
   'service':'android',
   'container_id':'macbook',
   '@timestamp':1580321240579
}

The query specified in elasticsearchRequest returns the average value of cpu_utilization across all documents with a @timestamp in the last five minutes. This value is metricized to the following form in SignalFx :

{
metric_name: avg_cpu_utilization,
dimensions:
  index: <name_of_index>
  metric_aggregation_type: avg
}

Data Model Transformation

Read through the following section to understand how this monitor transforms Elasticsearch responses to SignalFx datapoints.

At high level this monitor metricizes responses of the following types -

  1. Metric aggregations inside one or more Bucket aggregations such as the terms and filters aggregations. Dimensions on a datapoint are determined by the aggregation name (dimension name) and the key of each bucket (dimension value). The metric name is derived from the type of Metric aggregation name and it's values in case of multi-value aggregations. A dimension called metric_aggregation_type will also be set on the corresponding datapoints. See below for examples.

  2. Metric aggregations applied without any Bucket aggregation will be transformed just like in the above case.

  3. Bucket aggregations that do not have any Metric aggregations as sub aggregations will be transformed to a metric called <name_of_aggregation>.doc_count and will have bucket_aggregation_name dimension apart from the key of each bucket.

Note: Since Bucket aggregations determine dimensions in SignalFx, in most cases Bucket aggregations should be performed on string fields that represent a slice of the data from Elasticsearch.

Examples

  1. avg metric aggregation as a sub aggregation of terms bucket aggregation
{
  "aggs":{
    "host" : {
      "terms":{"field" : "host"},
      "aggs": {
        "average_cpu_usage": {
          "avg": {
            "field": "cpu_utilization"
          }
        }
      }
    }
  }
}

The above query will result in a metric called elasticsearch_query.average_cpu_usage and each datapoint will have a host dimension with its value being the key of a bucket in the response. The type of the metric aggregation (avg) will be set on the datapoint as metric_aggregation_type dimension. If the response looked like the below json, 4 datapoints would be collected, each with a different value for host.

...
"aggregations" : {
  "host" : {
    "doc_count_error_upper_bound" : 0,
    "sum_other_doc_count" : 0,
    "buckets" : [
      {
        "key" : "helsniki",
        "doc_count" : 13802,
        "average_cpu_usage" : {
          "value" : 49.77438052456166
        }
      },
      {
        "key" : "lisbon",
        "doc_count" : 13802,
        "average_cpu_usage" : {
          "value" : 49.919866685987536
        }
      },
      {
        "key" : "madrid",
        "doc_count" : 13802,
        "average_cpu_usage" : {
          "value" : 49.878350963628456
        }
      },
      {
        "key" : "nairobi",
        "doc_count" : 13802,
        "average_cpu_usage" : {
          "value" : 49.99789885523837
        }
      }
    ]
  }
}
...
  1. extended_stats metric aggregation as a sub aggregation of terms bucket aggregation
{
 "aggs":{
   "host" : {
     "terms":{"field" : "host"},
     "aggs": {
       "cpu_usage_stats": {
         "extended_stats": {
           "field": "cpu_utilization"
         }
       }
     }
   }
 }
}
...
"aggregations" : {
  "host" : {
    "doc_count_error_upper_bound" : 0,
    "sum_other_doc_count" : 0,
    "buckets" : [
      {
        "key" : "helsniki",
        "doc_count" : 13996,
        "cpu_usage_stats" : {
          "count" : 13996,
          "min" : 0.0,
          "max" : 100.0,
          "avg" : 49.86660474421263,
          "sum" : 697933.0
        }
      },
      {
        "key" : "lisbon",
        "doc_count" : 13996,
        "cpu_usage_stats" : {
          "count" : 13996,
          "min" : 0.0,
          "max" : 100.0,
          "avg" : 49.88225207202058,
          "sum" : 698152.0
        }
      },
      {
        "key" : "madrid",
        "doc_count" : 13996,
        "cpu_usage_stats" : {
          "count" : 13996,
          "min" : 0.0,
          "max" : 100.0,
          "avg" : 49.92469276936267,
          "sum" : 698746.0
        }
      },
      {
        "key" : "nairobi",
        "doc_count" : 13996,
        "cpu_usage_stats" : {
          "count" : 13996,
          "min" : 0.0,
          "max" : 100.0,
          "avg" : 49.98320948842527,
          "sum" : 699565.0
        }
      }
    ]
  }
}
...

In this case, each bucket will result 5 metrics -

  1. cpu_usage_stats.count
  2. cpu_usage_stats.min
  3. cpu_usage_stats.max
  4. cpu_usage_stats.avg
  5. cpu_usage_stats.sum

The dimensions are derived in the same manner as the previous example.

Configuration

To activate this monitor in the Smart Agent, add the following to your agent config:

monitors:  # All monitor config goes under this key
 - type: elasticsearch-query
   ...  # Additional config

For a list of monitor options that are common to all monitors, see Common Configuration.

Config option Required Type Description
httpTimeout no int64 HTTP timeout duration for both read and writes. This should be a duration string that is accepted by https://golang.org/pkg/time/#ParseDuration (default: 10s)
username no string Basic Auth username to use on each request, if any.
password no string Basic Auth password to use on each request, if any.
useHTTPS no bool If true, the agent will connect to the server using HTTPS instead of plain HTTP. (default: false)
httpHeaders no map of strings A map of HTTP header names to values. Comma separated multiple values for the same message-header is supported.
skipVerify no bool If useHTTPS is true and this option is also true, the exporter's TLS cert will not be verified. (default: false)
caCertPath no string Path to the CA cert that has signed the TLS cert, unnecessary if skipVerify is set to false.
clientCertPath no string Path to the client TLS cert to use for TLS required connections
clientKeyPath no string Path to the client TLS key to use for TLS required connections
host yes string
port yes string
index no string Index that's being queried. If none is provided, given query will be applied across all indexes. To apply the search query to multiple indices, provide a comma separated list of indices (default: _all)
elasticsearchRequest yes string Takes in an Elasticsearch request body search request. See [here] (https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html) for details.

The agent does not do any built-in filtering of metrics coming out of this monitor.