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服务器时仍会保留该事件。