文档文档

Elasticsearch 输出插件

此插件使用 Elastic 客户端库通过 HTTP 将指标写入 Elasticsearch。该插件支持从 v5.x 到 v7.x 的 Elasticsearch 版本。

引入于: Telegraf v0.1.5 标签: 数据存储, 日志记录 操作系统支持: all

Elasticsearch 索引和模板

按时间范围划分的索引

此插件可以按时间范围管理索引,这与其他使用 Elasticsearch 的工具中常见的做法类似。

收集到的指标的 timestamp 将用于决定索引目标。

有关 Elasticsearch 中此用法的更多信息,请查看 文档

模板管理

索引模板在 Elasticsearch 中用于定义索引的设置和映射以及字段应如何被分析。有关此工作原理的更多信息,请参阅 文档

此插件可以创建一个用于 telegraf 指标的可用模板。它使用 Elasticsearch 的动态模板功能为标签和指标字段设置正确的类型。如果指定的模板已存在,除非您配置插件进行覆盖,否则它不会覆盖。因此,如有必要,您可以在创建后自定义此模板。

telegraf 在 Elasticsearch 5.x 上创建的索引模板示例

{
  "order": 0,
  "template": "telegraf-*",
  "settings": {
    "index": {
      "mapping": {
        "total_fields": {
          "limit": "5000"
        }
      },
      "auto_expand_replicas" : "0-1",
      "codec" : "best_compression",
      "refresh_interval": "10s"
    }
  },
  "mappings": {
    "_default_": {
      "dynamic_templates": [
        {
          "tags": {
            "path_match": "tag.*",
            "mapping": {
              "ignore_above": 512,
              "type": "keyword"
            },
            "match_mapping_type": "string"
          }
        },
        {
          "metrics_long": {
            "mapping": {
              "index": false,
              "type": "float"
            },
            "match_mapping_type": "long"
          }
        },
        {
          "metrics_double": {
            "mapping": {
              "index": false,
              "type": "float"
            },
            "match_mapping_type": "double"
          }
        },
        {
          "text_fields": {
            "mapping": {
              "norms": false
            },
            "match": "*"
          }
        }
      ],
      "_all": {
        "enabled": false
      },
      "properties": {
        "@timestamp": {
          "type": "date"
        },
        "measurement_name": {
          "type": "keyword"
        }
      }
    }
  },
  "aliases": {}
}

示例事件

此插件将按以下方式格式化事件

{
  "@timestamp": "2017-01-01T00:00:00+00:00",
  "measurement_name": "cpu",
  "cpu": {
    "usage_guest": 0,
    "usage_guest_nice": 0,
    "usage_idle": 71.85413456197966,
    "usage_iowait": 0.256805341656516,
    "usage_irq": 0,
    "usage_nice": 0,
    "usage_softirq": 0.2054442732579466,
    "usage_steal": 0,
    "usage_system": 15.04879301548127,
    "usage_user": 12.634822807288275
  },
  "tag": {
    "cpu": "cpu-total",
    "host": "elastichost",
    "dc": "datacenter1"
  }
}
{
  "@timestamp": "2017-01-01T00:00:00+00:00",
  "measurement_name": "system",
  "system": {
    "load1": 0.78,
    "load15": 0.8,
    "load5": 0.8,
    "n_cpus": 2,
    "n_users": 2
  },
  "tag": {
    "host": "elastichost",
    "dc": "datacenter1"
  }
}

Timestamp 时区

Elasticsearch 文档使用 RFC3339 时间戳,其中包含时区信息(例如 2017-01-01T00:00:00-08:00)。默认情况下,将使用 Telegraf 系统配置的时区。

然而,这可能并不总是可取的:Elasticsearch 会保留时区信息并在返回相关文档时包含它。这可能导致某些管道出现问题。特别是那些不解析检索到的时间戳,而是假定返回的时区始终一致的管道。

Telegraf 会尊重环境变量 TZ 中配置的时区,因此可以在不更改主机系统配置的时区的情况下修改发送到 Elasticsearch 的时区。

export TZ="America/Los_Angeles"
export TZ="UTC"

如果 Telegraf 作为系统服务运行,在 Linux 上可以按以下方式配置:

echo TZ="UTC" | sudo tee -a /etc/default/telegraf

OpenSearch 支持

OpenSearch 是由 AWS 托管的 Elasticsearch 的一个分支。OpenSearch 服务器将向客户端报告其 AWS 特定版本(例如 v1.0)。实际上,实际的基础 Elasticsearch 版本是 v7.1。这会破坏 Telegraf 和其他需要知道其正在交互的主版本号的 Elasticsearch 客户端。

Amazon 创建了一个 兼容模式,以允许现有 Elasticsearch 客户端在需要检查版本时正常工作。要启用兼容模式,用户需要将 override_main_response_version 设置为 true

在现有集群上运行

PUT /_cluster/settings
{
  "persistent" : {
    "compatibility.override_main_response_version" : true
  }
}

在新集群上,请在高级选项中将选项设置为 true

POST https://es.us-east-1.amazonaws.com/2021-01-01/opensearch/upgradeDomain
{
  "DomainName": "domain-name",
  "TargetVersion": "OpenSearch_1.0",
  "AdvancedOptions": {
    "override_main_response_version": "true"
   }
}

全局配置选项

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

Secret-store 支持

此插件支持来自 secret-stores 的 usernamepasswordauth_bearer_token 选项的 secret。有关如何使用它们的更多详细信息,请参阅 secret-store 文档

配置

# Configuration for Elasticsearch to send metrics to.
[[outputs.elasticsearch]]
  ## The full HTTP endpoint URL for your Elasticsearch instance
  ## Multiple urls can be specified as part of the same cluster,
  ## this means that only ONE of the urls will be written to each interval
  urls = [ "http://node1.es.example.com:9200" ] # required.
  ## Elasticsearch client timeout, defaults to "5s" if not set.
  timeout = "5s"
  ## Set to true to ask Elasticsearch a list of all cluster nodes,
  ## thus it is not necessary to list all nodes in the urls config option
  enable_sniffer = false
  ## Set to true to enable gzip compression
  enable_gzip = false
  ## Set the interval to check if the Elasticsearch nodes are available
  ## Setting to "0s" will disable the health check (not recommended in production)
  health_check_interval = "10s"
  ## Set the timeout for periodic health checks.
  # health_check_timeout = "1s"
  ## HTTP basic authentication details.
  ## HTTP basic authentication details
  # username = "telegraf"
  # password = "mypassword"
  ## HTTP bearer token authentication details
  # auth_bearer_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

  ## Index Config
  ## The target index for metrics (Elasticsearch will create if it not exists).
  ## You can use the date specifiers below to create indexes per time frame.
  ## The metric timestamp will be used to decide the destination index name
  # %Y - year (2016)
  # %y - last two digits of year (00..99)
  # %m - month (01..12)
  # %d - day of month (e.g., 01)
  # %H - hour (00..23)
  # %V - week of the year (ISO week) (01..53)
  ## Additionally, you can specify a tag name using the notation {{tag_name}}
  ## which will be used as part of the index name. If the tag does not exist,
  ## the default tag value will be used.
  # index_name = "telegraf-{{host}}-%Y.%m.%d"
  # default_tag_value = "none"
  index_name = "telegraf-%Y.%m.%d" # required.

  ## Optional Index Config
  ## Set to true if Telegraf should use the "create" OpType while indexing
  # use_optype_create = false

  ## 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

  ## Template Config
  ## Set to true if you want telegraf to manage its index template.
  ## If enabled it will create a recommended index template for telegraf indexes
  manage_template = true
  ## The template name used for telegraf indexes
  template_name = "telegraf"
  ## Set to true if you want telegraf to overwrite an existing template
  overwrite_template = false
  ## If set to true a unique ID hash will be sent as sha256(concat(timestamp,measurement,series-hash)) string
  ## it will enable data resend and update metric points avoiding duplicated metrics with different id's
  force_document_id = false

  ## Specifies the handling of NaN and Inf values.
  ## This option can have the following values:
  ##    none    -- do not modify field-values (default); will produce an error if NaNs or infs are encountered
  ##    drop    -- drop fields containing NaNs or infs
  ##    replace -- replace with the value in "float_replacement_value" (default: 0.0)
  ##               NaNs and inf will be replaced with the given number, -inf with the negative of that number
  # float_handling = "none"
  # float_replacement_value = 0.0

  ## Pipeline Config
  ## To use a ingest pipeline, set this to the name of the pipeline you want to use.
  # use_pipeline = "my_pipeline"
  ## Additionally, you can specify a tag name using the notation {{tag_name}}
  ## which will be used as part of the pipeline name. If the tag does not exist,
  ## the default pipeline will be used as the pipeline. If no default pipeline is set,
  ## no pipeline is used for the metric.
  # use_pipeline = "{{es_pipeline}}"
  # default_pipeline = "my_pipeline"
  #
  ## Custom HTTP Headers
  ## To pass custom HTTP headers please define it in a given below section
  # [outputs.elasticsearch.headers]
  #    "X-Custom-Header" = ["custom-value1", "custom-value2"]

  ## Template Index Settings
  ## Overrides the template settings.index section with any provided options.
  ## Defaults provided here in the config
  # template_index_settings = {
  #   refresh_interval = "10s",
  #   mapping.total_fields.limit = 5000,
  #   auto_expand_replicas = "0-1",
  #   codec = "best_compression"
  # }

权限

如果您在 Elasticsearch 集群中使用身份验证,则需要创建一个账户并创建一个至少具有 Cluster Privileges 类别中 manage 角色的角色。否则,您的账户将无法连接到 Elasticsearch 集群并将日志发送到集群。之后,您需要为您的特定索引模式添加“create_indice”和“write”权限。

必需参数

  • urls:一个包含来自您的 Elasticsearch 实例的一个或多个节点的完整 HTTP URL 的列表。
  • index_name:指标的目标索引。您可以使用下面的日期说明符按时间范围创建索引。
  %y - last two digits of year (00..99)
  %m - month (01..12)
  %d - day of month (e.g., 01)
  %H - hour (00..23)
  %V - week of the year (ISO week) (01..53)

此外,您可以使用 {{tag_name}} 符号的标签来指定动态索引名称。这将把具有不同标签值的指标存储在不同的索引中。如果标签在特定指标中不存在,将使用 default_tag_value

可选参数

  • timeout:Elasticsearch 客户端超时,如果未设置,则默认为“5s”。
  • enable_sniffer:设置为 true 以从 Elasticsearch 获取所有集群节点列表,因此无需在 urls 配置选项中列出所有节点。
  • health_check_interval:设置检查节点是否可用的间隔(以秒为单位)。设置为 0 将禁用健康检查(不建议在生产环境中使用)。
  • username:HTTP 基本身份验证详细信息的用户名(例如,在使用 Shield 时)。
  • password:HTTP 基本身份验证详细信息的密码(例如,在使用 Shield 时)。
  • manage_template:如果希望 telegraf 管理其索引模板,则设置为 true。如果启用,它将为 telegraf 索引创建一个推荐的索引模板。
  • template_name:用于 telegraf 索引的模板名称。
  • overwrite_template:如果希望 telegraf 覆盖现有模板,则设置为 true。
  • force_document_id:设置为 true 将计算一个 sha256(concat(timestamp,measurement,series-hash)) 的唯一哈希值,启用重新发送或更新数据而不会在 ES 中产生重复文档。
  • float_handling:指定如何处理 NaN 和无穷大的字段值。"none"(默认)将不做任何操作,"drop" 将删除该字段,replace 将用 float_replacement_value 中的数字替换该字段值。
  • float_replacement_value:如果 float_handling 设置为 replace,则用于替换 NaNinf 的值(默认为 0.0)。负无穷将被替换为该数字中的负值,以保持字段原始值的符号。
  • use_optype_create:如果设置,将在索引到 Elasticsearch 时使用“create”操作类型,这在使用 Elasticsearch 数据流功能时是必需的。
  • use_pipeline:如果设置,则将使用设置的值作为发送事件到 elasticsearch 时调用的 pipeline。此外,您可以使用 {{tag_name}} 符号指定动态 pipeline 名称。如果标签在特定指标中不存在,将使用 default_pipeline
  • default_pipeline:如果动态 pipeline 名称的标签在特定指标中不存在,则使用此值。
  • headers:自定义 HTTP 标头,在每次请求前传递给 Elasticsearch 标头。

已知问题

由 golang JSON 编码器以十进制格式编码的整数值(大于 2^63 且小于 1e21 或其对应负数的精确相同窗口)未被 Elasticsearch 动态字段映射完全支持。如果 Telegraf 索引上尚未创建字段映射,这会导致具有此类值的指标被丢弃。如果是这种情况,您将在 Elasticsearch 端看到类似以下的异常:

{"error":{"root_cause":[{"type":"mapper_parsing_exception","reason":"failed to parse"}],"type":"mapper_parsing_exception","reason":"failed to parse","caused_by":{"type":"illegal_state_exception","reason":"No matching token for number_type [BIG_INTEGER]"}},"status":400}

一旦 Elasticsearch 接收到受支持的 JSON 值,Telegraf 索引上就会创建正确的字段映射,并且后续的插入将正常工作,因为字段映射已经存在。

此问题是由 Elasticsearch 尝试检测整数字段的方式以及 golang 如何在 JSON 中编码数字引起的。目前没有明确的解决方法。


此页面是否有帮助?

感谢您的反馈!


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