Logstash 参考指南（Elasticsearch输入插件）

Elasticsearch输入插件

• 插件版本：v4.3.0
• 发布于：2019-02-04
• 更新日志

对于其他版本，请参阅版本化插件文档。

获取帮助

有关插件的问题，请在讨论论坛中打开一个主题，对于错误或特性请求，请在Github中打开一个问题，关于Elastic支持的插件列表，请考虑Elastic支持矩阵。

描述

兼容性说明

从Elasticsearch 5.3开始，有一个名为http.content_type.required的HTTP设置，如果此选项设置为true，并且你使用的是Logstash 2.4到5.2，则需要将Elasticsearch输入插件更新到4.0.2或更高版本。

从Elasticsearch集群中读取搜索查询的结果，这对于重放测试日志、重建索引等非常有用。你可以使用cron语法定期调度摄取（请参阅调度设置）或运行查询一次以将数据加载到Logstash中。

示例：

input {
  # 读取Elasticsearch中与给定查询匹配的所有文档
  elasticsearch {
    hosts => "localhost"
    query => '{ "query": { "match": { "statuscode": 200 } }, "sort": [ "_doc" ] }'
  }
}

这将使用以下格式创建Elasticsearch查询：

curl 'http://localhost:9200/logstash-*/_search?&scroll=1m&size=1000' -d '{
  "query": {
    "match": {
      "statuscode": 200
    }
  },
  "sort": [ "_doc" ]
}'

调度

可以调度此插件的输入根据特定调度定期运行，此调度语法由rufus-scheduler提供支持，语法类似cron，有一些特定于Rufus的扩展（例如时区支持）。

示例：

* 5 * 1-3 *	将从1月到3月的每天凌晨5点每分钟执行一次
0 * * * *	将在每天每小时的第0分钟执行
0 6 * * * America/Chicago	将在每天上午6:00（UTC/GMT-5）执行

可以在此处找到描述此语法的更多文档。

Elasticsearch输入配置选项

此插件支持以下配置选项以及稍后描述的通用选项。

设置	输入类型	必须
ca_file	一个有效的文件系统路径	No
docinfo	boolean	No
docinfo_fields	数组	No
docinfo_target	string	No
hosts	数组	No
index	string	No
password	string	No
query	string	No
schedule	string	No
scroll	string	No
size	number	No
slices	number	No
ssl	boolean	No
user	string	No

另请参阅通用选项以获取所有输入插件支持的选项列表。

ca_file

• 值类型是路径
• 此设置没有默认值
• PEM编码格式的SSL证书颁发机构文件，必要时还必须包含任何链证书。

docinfo

• 值类型是boolean
• 默认值为false

• 如果设置，事件中包含Elasticsearch文档信息，例如索引、类型和ID。关于元数据，可能需要注意的是，如果你正在提取文档，意图重新索引它们（或只是更新它们），那么elasticsearch输出中的action选项想要知道如何处理这些事情，可以使用添加到元数据的字段动态分配它。

  示例：

  input {
    elasticsearch {
      hosts => "es.production.mysite.org"
      index => "mydata-2018.09.*"
      query => '{ "query": { "query_string": { "query": "*" } } }'
      size => 500
      scroll => "5m"
      docinfo => true
    }
  }
  output {
    elasticsearch {
      index => "copy-of-production.%{[@metadata][_index]}"
      document_type => "%{[@metadata][_type]}"
      document_id => "%{[@metadata][_id]}"
    }
  }

  从Logstash 6.0开始，由于删除了Logstash 6.0中的类型，因此不推荐使用 document_type选项，它将在Logstash的下一个主要版本中删除。

docinfo_fields

• 值类型是数组
• 默认值为["_index", "_type", "_id"]
• 如果通过启用docinfo选项请求文档元数据存储，则此选项会列出要在当前事件中保存的元数据字段，有关详细信息，请参阅Elasticsearch文档中的文档元数据。

docinfo_target

• 值类型是string
• 默认值为"@metadata"
• 如果通过启用docinfo选项请求文档元数据存储，此选项命名在其下将元数据字段存储为子字段的字段。

hosts

• 值类型是数组
• 此设置没有默认值
• 用于查询的一个或多个Elasticsearch主机的列表，每个主机可以是IP、HOST、IP:port或HOST:port，端口默认为9200。

ca_file

• 值类型是路径
• 此设置没有默认值
• PEM编码格式的SSL证书颁发机构文件，必要时还必须包含任何链证书。

index

• 值类型是string
• 默认值为"logstash-*"
• 要搜索的索引或别名，有关如何引用多个索引的更多信息，请参阅Elasticsearch文档中的多索引文档。

password

• 值类型是password
• 此设置没有默认值
• 在向Elasticsearch服务器进行身份验证时，与user选项中的用户名一起使用的密码，如果设置为空字符串，则将禁用身份验证。

query

• 值类型是string
• 默认值为'{ "sort": [ "_doc" ] }'
• 要执行的查询，有关更多信息，请阅读Elasticsearch查询DSL文档。

schedule

• 值类型是string
• 此设置没有默认值
• 以Cron格式定期运行语句的调度，例如："* * * * *"（每分钟执行一次查询），默认情况下没有调度，如果没有给出调度，那么该语句只运行一次。

scroll

• 值类型是string
• 默认值为"1m"
• 此参数控制滚动请求的保持活动时间（以秒为单位）并启动滚动过程，每次往返（即在前一个滚动请求到下一个滚动请求之间）应用的超时。

size

• 值类型是number
• 默认值为1000
• 这允许你设置每个滚动返回的最大命中数。

slices

• 值类型是number
• 没有默认值
• 合理的值范围从2到大约8

• 在某些情况下，可以通过使用Sliced Scroll API同时消费查询的多个不同切片来提高总体吞吐量，特别是如果管道花费大量时间等待Elasticsearch提供结果。如果设置，则slices参数告诉插件将工作分成多少个切片，并将并行地从切片生成事件，直到所有切片完成滚动。

  Elasticsearch手册指出，当滚动查询使用的切片多于索引中的碎片时，对查询和Elasticsearch集群可能会产生负面的性能影响。

• 如果未设置slices参数，则插件不会将切片指令注入查询。

ssl

• 值类型是boolean
• 默认值为false
• 如果启用，则在与Elasticsearch服务器通信时将使用SSL（即将使用HTTPS而不是普通HTTP）。

user

• 值类型是string
• 此设置没有默认值
• 在向Elasticsearch服务器进行身份验证时，与password选项中的密码一起使用的用户名，如果设置为空字符串，则将禁用身份验证。

通用选项

所有输入插件都支持以下配置选项：

设置	输入类型	必需
add_field	hash	No
codec	codec	No
enable_metric	boolean	No
id	字符串	No
tags	数组	No
type	字符串	No

细节

add_field

• 值类型是hash
• 默认值为{}
• 向事件添加字段。

codec

• 值类型是codec
• 默认值为"json"
• 用于输入数据的编解码器，输入编解码器是一种在数据进入输入之前解码数据的便捷方法，无需在Logstash管道中使用单独的过滤器。

enable_metric

• 值类型是boolean
• 默认值为true
• 默认情况下，会记录能记录的所有指标，但是你可以禁用特定插件的指标收集。

id

• 值类型是string
• 此设置没有默认值

• 为插件配置添加唯一ID，如果未指定ID，Logstash将生成一个ID，强烈建议在配置中设置此ID，当你有两个或更多相同类型的插件时，这尤其有用，例如，如果你有2个elasticsearch输入。在这种情况下添加命名ID将有助于在使用监控API时监控Logstash。

  input {
   elasticsearch {
     id => "my_plugin_id"
   }
  }

tags

• 值类型是数组
• 此设置没有默认值
• 为你的事件添加任意数量的任意标签，这有助于以后处理。

type

• 值类型是string
• 此设置没有默认值
• 将type字段添加到此输入处理的所有事件，类型主要用于过滤器激活，类型存储为事件本身的一部分，因此你也可以使用该类型在Kibana中搜索它。如果你尝试在已有类型的事件上设置类型（例如，当你将事件从shipper发送到索引器时），则新输入将不会覆盖现有类型，shipper设置的类型即使在发送到另一个Logstash服务器时仍会保留该事件。