文档文档

OpenSearch 查询输入插件

此插件查询 OpenSearch 端点,以从存储在 OpenSearch 集群中的数据中派生指标,例如搜索查询的命中次数、数值字段的统计信息、文档计数等。

此插件已针对 OpenSearch 2.5.0 和 1.3.7 进行测试,但较新版本也应该有效。

推出时间: Telegraf v1.26.0 标签: datastore 操作系统支持: all

全局配置选项

插件支持其他全局和插件配置设置,用于修改指标、标签和字段,创建别名以及配置插件顺序等任务。更多详情请参阅 CONFIGURATION.md

配置

# Derive metrics from aggregating OpenSearch query results
[[inputs.opensearch_query]]
  ## OpenSearch cluster endpoint(s). Multiple urls can be specified as part
  ## of the same cluster.  Only one successful call will be made per interval.
  urls = [ "https://node1.os.example.com:9200" ] # required.

  ## OpenSearch client timeout, defaults to "5s".
  # timeout = "5s"

  ## HTTP basic authentication details
  # username = "admin"
  # password = "admin"

  ## Skip TLS validation.  Useful for local testing and self-signed certs.
  # insecure_skip_verify = false

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

    ## OpenSearch index or index pattern to search
    index = "index-*"

    ## The date/time field in the OpenSearch index (mandatory).
    date_field = "@timestamp"

    ## If the field used for the date/time field in OpenSearch is also using
    ## a custom date/time format it may be required to provide the format to
    ## correctly parse the field.
    ##
    ## If using one of the built in OpenSearch formats this is not required.
    ## https://opensearch.org.cn/docs/2.4/opensearch/supported-field-types/date/#built-in-formats
    # date_field_custom_format = ""

    ## Time window to query (eg. "1m" to query documents from last minute).
    ## Normally 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
    ## Must be set if 'metric_fields' is set
    ## Valid values are: avg, sum, min, max, sum
    # metric_function = "avg"

    ## Fields to be used as tags.  Must be text, non-analyzed fields. Metric
    ## aggregations are performed per tag
    # tags = ["field.keyword", "field2.keyword"]

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

    ## String value of the tag when the tag does not exist
    ## Required when include_missing_tag is true
    # missing_tag_value = "null"

支持的查询

以下查询是受支持的

  • 返回搜索查询的命中次数
  • 计算数字字段的 avg/max/min/sum,按查询过滤,按标签聚合
  • value_count 返回特定字段的文档数
  • stats (一次查询返回 summinmaxavgvalue_count)
  • extended_stats (stats 加上诸如平方和、方差和标准差之类的统计数据)
  • percentiles 返回第 1、5、25、50、75、95 和 99 百分位数

必需参数

  • measurement_name: 用于存储聚合查询结果的目标度量。
  • index: 在 OpenSearch 上查询的索引名称
  • query_period: 查询的时间窗口(例如,“1m”查询最后 1 分钟的文档)。通常应设置为与 collection 相同
  • date_field: OpenSearch 索引中的日期/时间字段

可选参数

  • date_field_custom_format: 如果使用 OpenSearch 的内置日期/时间格式之一,则不需要,但如果使用自定义日期/时间格式,则可能需要。格式语法使用 Joda 日期格式
  • filter_query: 用于过滤结果的 Lucene 查询(默认:“*”)
  • metric_fields: 用于执行指标聚合的字段列表(这些字段必须索引为数字字段)
  • metric_function: 将在定义的 metric_fields 上执行的单值指标聚合函数。当前支持的聚合包括“avg”、“min”、“max”、“sum”、“value_count”、“stats”、“extended_stats”、“percentiles”。(请参阅 聚合文档
  • tags: 将用作标签的字段列表(这些字段必须索引为非分析字段)。将为定义的每个标签执行“terms 聚合”
  • include_missing_tag: 设置为 true 以不忽略缺少上述标签的文档。(如果为 false,则在 doc_count 和指标聚合中将忽略没有指定标签字段的文档)
  • missing_tag_value: 当 include_missing_tag 设置为 true 时,将为缺少标签字段的文档设置的标签值。仅在此参数为 true 时使用。

配置示例

按 URI 和响应状态码搜索平均响应时间

[[inputs.opensearch_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"

按方法和 URI 搜索最大响应时间

[[inputs.opensearch_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"

在所有索引中搜索匹配过滤查询的文档数

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

搜索匹配过滤查询的文档数,按响应状态码返回

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

搜索所有文档并生成通用统计信息,按响应状态码返回

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

Metrics

所有指标都源自 OpenSearch 查询结果的聚合。查询必须符合相应的 OpenSearch 聚合,以获取更多信息。

指标名称由字段名称、指标聚合函数和结果字段名称组合而成。

对于简单指标,结果字段名称为 value,因此对名为 size 的字段进行 avg 计算将产生结果 size_value_avg

对于具有多个指标的函数,我们使用结果字段。例如,stats 函数返回五个不同的结果,因此对于字段 size,我们将看到五个指标字段,分别命名为 size_stats_minsize_stats_maxsize_stats_sumsize_stats_avgsize_stats_count

嵌套结果将基于其父字段名称构建,例如,百分位数的结构为

{
  "aggregations" : {
  "size_percentiles" : {
    "values" : {
      "1.0" : 21.984375,
      "5.0" : 27.984375,
      "25.0" : 44.96875,
      "50.0" : 64.22061688311689,
      "75.0" : 93.0,
      "95.0" : 156.0,
      "99.0" : 222.0
    }
  }
 }
}

因此,我们的结果将采用 size_percentiles_values_1.0 的形式。此结构适用于 percentilesextended_stats 函数。

注意:extended_stats 目前仅限于 2 个标准差。

示例输出

[[inputs.opensearch_query.aggregation]]
    measurement_name = "bytes_stats"
    index = "opensearch_dashboards_sample_data_logs"
    date_field = "timestamp"
    query_period = "10m"
    filter_query = "*"
    metric_fields = ["bytes"]
    metric_function = "stats"
    tags = ["response.keyword"]
bytes_stats,host=localhost,response_keyword=200 bytes_stats_sum=22231,doc_count=4i,bytes_stats_count=4,bytes_stats_min=941,bytes_stats_max=9544,bytes_stats_avg=5557.75 1672327840000000000
bytes_stats,host=localhost,response_keyword=404 bytes_stats_min=5330,bytes_stats_max=5330,bytes_stats_avg=5330,doc_count=1i,bytes_stats_sum=5330,bytes_stats_count=1 1672327840000000000

此页面是否有帮助?

感谢您的反馈!


InfluxDB 3.8 新特性

InfluxDB 3.8 和 InfluxDB 3 Explorer 1.6 的主要增强功能。

查看博客文章

InfluxDB 3.8 现已适用于 Core 和 Enterprise 版本,同时发布了 InfluxDB 3 Explorer UI 的 1.6 版本。本次发布着重于操作成熟度,以及如何更轻松地部署、管理和可靠地运行 InfluxDB。

更多信息,请查看

InfluxDB Docker 的 latest 标签将指向 InfluxDB 3 Core

在 **2026 年 2 月 3 日**,InfluxDB Docker 镜像的 latest 标签将指向 InfluxDB 3 Core。为避免意外升级,请在您的 Docker 部署中使用特定的版本标签。

如果使用 Docker 来安装和运行 InfluxDB,latest 标签将指向 InfluxDB 3 Core。为避免意外升级,请在您的 Docker 部署中使用特定的版本标签。例如,如果使用 Docker 运行 InfluxDB v2,请将 latest 版本标签替换为 Docker pull 命令中的特定版本标签 — 例如

docker pull influxdb:2