Documentation

Elasticsearch Query Input Plugin

This plugin allows to query an Elasticsearch instance to obtain metrics from data stored in the cluster. The plugins supports counting the number of hits for a search query, calculating statistics for numeric fields, filtered by a query, aggregated per tag and to count the number of terms for a particular field.

This plugins supports Elasticsearch 5.x and 6.x but is known to break on 7.x or higher.

Introduced in: Telegraf v1.20.0 Tags: datastore OS support: all

Global configuration options

Plugins support additional global and plugin configuration settings for tasks such as modifying metrics, tags, and fields, creating aliases, and configuring plugin ordering. See CONFIGURATION.md for more details.

Configuration

# Derive metrics from aggregating Elasticsearch query results
[[inputs.elasticsearch_query]]
  ## Full HTTP endpoint URL for your Elasticsearch instance
  ## Multiple urls can be specified as part of the same cluster, but only ONE
  ## will be queried in each interval.
  urls = [ "http://node1.es.example.com:9200" ]

  ## Timeout for operations
  # timeout = "5s"

  ## List all cluster nodes making it unnecessary to list all nodes in 'urls'
  # enable_sniffer = false

  ## Interval for checking availability of cluster nodes; only used if sniffer
  ## is enabled (0s will disable checks)
  # health_check_interval = "10s"

  ## HTTP basic authentication credentials
  # username = "telegraf"
  # password = "mypassword"

  ## Optional TLS Config
  # tls_ca = "/etc/telegraf/ca.pem"
  # tls_cert = "/etc/telegraf/cert.pem"
  # tls_key = "/etc/telegraf/key.pem"
  ## Use TLS but skip chain & host verification
  # insecure_skip_verify = false

  ## If 'use_system_proxy' is set to true, Telegraf will check env vars such as
  ## HTTP_PROXY, HTTPS_PROXY, and NO_PROXY (or their lowercase counterparts).
  ## If 'use_system_proxy' is set to false (default) and 'http_proxy_url' is
  ## provided, Telegraf will use the specified URL as HTTP proxy.
  # use_system_proxy = false
  # http_proxy_url = "http://localhost:8888"

  [[inputs.elasticsearch_query.aggregation]]
    ## measurement name for the results of the aggregation query
    measurement_name = "measurement"

    ## Elasticsearch indexes to query (accept wildcards)
    index = "index-*"

    ## Date/time field in the Elasticsearch index
    date_field = "@timestamp"

    ## Custom format for date/time field if used
    # date_field_custom_format = ""

    ## Time window to query (eg. "1m" to query documents from last minute).
    ## Should be set to same as collection interval
    query_period = "1m"

    ## Lucene query to filter results
    # filter_query = "*"

    ## Fields to aggregate values (must be numeric fields)
    # metric_fields = ["metric"]

    ## Aggregation function to use on the metric fields; required if
    ## 'metric_fields' is set. Available values: avg, sum, min, max, sum
    # metric_function = "avg"

    ## Text, non-analyzed fields to be used as tags
    # tags = ["field.keyword", "field2.keyword"]

    ## Do not ignore documents when the tag(s) above are missing
    # include_missing_tag = false

    ## Fallback value when the tag does not exist; ignored if
    ## include_missing_tag is false
    # missing_tag_value = "null"

Examples

Please note that the [[inputs.elasticsearch_query]] is still required for all of the examples below.

Search the average response time, per URI and per response status code

[[inputs.elasticsearch_query.aggregation]]
  measurement_name = "http_logs"
  index = "my-index-*"
  filter_query = "*"
  metric_fields = ["response_time"]
  metric_function = "avg"
  tags = ["URI.keyword", "response.keyword"]
  include_missing_tag = true
  missing_tag_value = "null"
  date_field = "@timestamp"
  query_period = "1m"

Search the maximum response time per method and per URI

[[inputs.elasticsearch_query.aggregation]]
  measurement_name = "http_logs"
  index = "my-index-*"
  filter_query = "*"
  metric_fields = ["response_time"]
  metric_function = "max"
  tags = ["method.keyword","URI.keyword"]
  include_missing_tag = false
  missing_tag_value = "null"
  date_field = "@timestamp"
  query_period = "1m"

Search number of documents matching a filter query in all indices

[[inputs.elasticsearch_query.aggregation]]
  measurement_name = "http_logs"
  index = "*"
  filter_query = "product_1 AND HEAD"
  query_period = "1m"
  date_field = "@timestamp"

Search number of documents matching a filter query, returning per response status code

[[inputs.elasticsearch_query.aggregation]]
  measurement_name = "http_logs"
  index = "*"
  filter_query = "downloads"
  tags = ["response.keyword"]
  include_missing_tag = false
  date_field = "@timestamp"
  query_period = "1m"

Required parameters

  • measurement_name: The target measurement to be stored the results of the aggregation query.
  • index: The index name to query on Elasticsearch
  • query_period: The time window to query (eg. “1m” to query documents from last minute). Normally should be set to same as collection
  • date_field: The date/time field in the Elasticsearch index

Optional parameters

  • date_field_custom_format: Not needed if using one of the built in date/time formats of Elasticsearch, but may be required if using a custom date/time format. The format syntax uses the Joda date format.
  • filter_query: Lucene query to filter the results (default: “*”)
  • metric_fields: The list of fields to perform metric aggregation (these must be indexed as numeric fields)
  • metric_function: The single-value metric aggregation function to be performed on the metric_fields defined. Currently supported aggregations are “avg”, “min”, “max”, “sum”. (see the aggregation docs)
  • tags: The list of fields to be used as tags (these must be indexed as non-analyzed fields). A “terms aggregation” will be done per tag defined
  • include_missing_tag: Set to true to not ignore documents where the tag(s) specified above does not exist. (If false, documents without the specified tag field will be ignored in doc_count and in the metric aggregation)
  • missing_tag_value: The value of the tag that will be set for documents in which the tag field does not exist. Only used when include_missing_tag is set to true.

Metrics

The format of metrics produced by this plugin depends on the content of the database and the queries used.

Example Output


Was this page helpful?

Thank you for your feedback!


InfluxDB OSS 2.9.0: API tokens are hashed by default

Stronger token security in InfluxDB OSS 2.9.0 — tokens are hashed on disk by default. Existing tokens are hashed on first startup and can’t be recovered afterward. Capture any plaintext tokens you still need before you upgrade.

View InfluxDB OSS 2.9.0 release notes

Hashed tokens authenticate exactly like unhashed tokens — clients and integrations keep working.

Also new in 2.9.0:

  • Configurable backup compression
  • Restore support for backups containing hashed tokens
  • Tighter Edge Data Replication queue validation
  • Flux upgrade
  • Compaction reliability improvements

Key enhancements in Explorer 1.9

Explorer 1.9 is now available with InfluxQL support, an AI-assisted Flux to SQL converter (beta), and new live sample data simulators.

View Explorer 1.9 release notes

Explorer 1.9 includes new features and improvements that make it easier to query, visualize, and manage data.

Highlights:

  • Flux to SQL converter (beta): Convert Flux queries to SQL with an AI-assisted converter.
  • InfluxQL support: Query data with InfluxQL in the Data Explorer and dashboards, and save and load InfluxQL queries.
  • InfluxQL visualizations: Render line and bar charts from InfluxQL results with per-tag series grouping.
  • Query error history: Review a history of query errors in the query tool.
  • Live sample data simulators: Generate continuous live sample data with new bird data and signal generator simulators.

For more details, see Explorer 1.9 release notes

InfluxDB 3.10 is now available

InfluxDB 3 Core 3.10 adds an automatic catalog format upgrade, a configurable query-concurrency limit, and processing engine improvements.

Key updates in InfluxDB 3 Core 3.10:

  • Catalog format upgrade: the on-disk catalog automatically upgrades from format v2 to v3 on first 3.10 startup. Migration is one-way—back up your catalog before upgrading.
  • --max-concurrent-queries: limit concurrent queries (adjustable at runtime).
  • GET /ready endpoint for readiness probes.
  • Processing engine: cross-database queries and trigger lockdown flags.

For more information, see the InfluxDB 3 Core release notes.

InfluxDB 3.10 is now available

InfluxDB 3 Enterprise 3.10 adds automated backup and restore, row-level deletions, and user management, with an automatic catalog format upgrade and performance preview improvements.

Key updates in InfluxDB 3 Enterprise 3.10:

  • Catalog format upgrade: the on-disk catalog automatically upgrades from format v2 to v3 on first 3.10 startup. Migration is one-way—back up your catalog before upgrading.
  • Automated backup and restore (beta)
  • Row-level deletions
  • User management (authentication and RBAC) — preview
  • Performance preview improvements

Backup and restore, row-level deletions, and the performance preview require the Enterprise storage engine upgrade (opt-in beta). Beta and preview features are subject to breaking changes and aren’t recommended for production use.

For more information, see the InfluxDB 3 Enterprise release notes

Telegraf Enterprise is now generally available

Telegraf Enterprise is now generally available, along with Telegraf Controller v1.0.

Telegraf Enterprise combines Telegraf Controller, a centralized management console for Telegraf, with official support from InfluxData. Manage configurations, monitor fleet health, and operate tens of thousands of Telegraf agents from a single system.

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On September 15, 2026, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2