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/telegrafOpenSearch 支持
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 的 username、password 和 auth_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,则用于替换NaN和inf的值(默认为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 中编码数字引起的。目前没有明确的解决方法。
此页面是否有帮助?
感谢您的反馈!
支持和反馈
感谢您成为我们社区的一员!我们欢迎并鼓励您对 Telegraf 和本文档提出反馈和 bug 报告。要获取支持,请使用以下资源
具有年度合同或支持合同的客户可以 联系 InfluxData 支持。