记Filebeat的prospectors部分配置说明

Filebeat的工作原理

Filebeat是一个日志文件收集工具，filebeat最初是基于logstash-forwarder源码的日志数据shipper，部署在所要采集日志的服务器上，采集指定的日志文件信息转发给logstash进行分析然后再发送到elasticsearch构建索引，或者直接发送到elasticsearch，也可以发送到redis上，用redis作为消息队列

Filebeat搜集日志的主要角色有harvester和prospectors

harvester

harvester负责读取单个文件的内容。harvester逐行读取每个文件，并将内容发送到输出。每个文件启动一台harvester。harvester负责打开关闭文件，harvester运行时会保持文件的文件描述符保持打开的状态，而且文件在被扫描时被删除或重命名了，Filebeat会继续读取文件， 这会导致在harvester关闭之前，被删除的文件的磁盘空间不会被释放。 默认情况下，Filebeat将文件保持打开状态，直到达到close_inactive。

prospectors

prospectors目前支持5种类型：

• log: Reads every line of the log file (default).
• stdin: Reads the standard in.
• redis: Reads slow log entries from redis (experimental).
• udp: Reads events over UDP. Also see max_message_sizeedit.
• docker: Reads logs from Docker. Also see containersedit (experimental).

prospectors检查每个文件以查看是否需要启动harvester，是否已经运行harvester，或者文件是否可以被忽略。 只有在harvester关闭后文件的大小发生了变化，才会选择新行。
prospectors只能读取本地文件
Filebeat保持每个文件的状态并经常将状态刷新到磁盘的上注册表中。 该状态用于记住harvester正在读取的最后偏移量，便于确保发送所有日志行。但是如果你收集的日志，每天新建了大量的文件，会发现注册表会非常的巨大。要减小注册表文件的大小，有两个可用的配置选项：clean_removed和clean_inactive。 对于不再接触并忽略的旧文件，使用clean_inactive。 如果旧文件从磁盘中删除，请使用clean_removed选项。

Filebeat保证事件至少会被传送到你所配置的output目标一次，并且不会丢失数据。 Filebeat能够实现此行为，因为它将每个事件的传递状态存储在注册表文件中。 在定义的output被阻止并且未确认所有事件接收到情况下，Filebeat将继续尝试发送事件，直到输出确认已收到事件。 如果Filebeat在发送事件的过程中关闭，它不会在关闭之前等待output目标确认所有事件的接受，Filebeat在重新启动后，他会重新发送之前没被输出目标确认接受的事件。 这可以确保每个事件至少发送一次，但也可能会将重复事件发送到输出目标。 您可以通过设置shutdown_timeout选项来配置Filebeat以在关闭之前的等待时间。

每个prospectors为每个文件保持一个状态。 由于文件可以被重命名或移动，因此文件名和路径不足以识别文件。 对于每个文件，Filebeat存储唯一标识符以检测文件是否先前已被harvester扫描过。

prospectors的一些配置选项

我们可以在filebeat.yaml中定义prospectors的配置选项，来实现对特定的日志进行特定的扫描收集，下文只列出部分配置选项，详细请看官方文件

一. close_ *

close_ * 配置选项用于在某个标准或时间后关闭harvester。 关闭harvester意味着关闭文件处理程序。 如果收割机关闭后文件被更新，则在scan_frequency过后，文件将再次被扫描。 但是，如果在harvester关闭的情况下移动或删除文件，Filebeat将无法再次扫描文件，harvester将丢失未读取的数据。

close_inactive
启用此选项时，如果文件在指定的持续时间内没有更新，Filebeat会关闭文件句柄。如果关闭的文件再次发生变化，则会启动一台新的harvester，并在scan_frequency过去后采集最新的更改。建议将close_inactive设置为大于日志文件两次更新间隔时间的最大值。例如，如果日志文件每隔几秒更新一次，则可以安全地将close_inactive设置为1m。如果有更新频率非常不同的日志文件，则可以使用具有不同值的多个prospectors配置。将close_inactive设置为较低的值意味着文件句柄会更快关闭。但是，这具有副作用，即如果harvester关闭，则不会实时发送新的日志行。关闭文件的时间戳不取决于文件的修改时间，关闭文件的时间戳为修改文件的时间+close_inactive。例如，如果close_inactive设置为5分钟，那么在收割机读取文件的最后一行之后，5分钟的倒计时开始。您可以使用时间字符串，如2h（2小时）和5m（5分钟）。默认值是5m。

close_renamed
启用此选项时，文件重命名时Filebeat会关闭文件处理程序。 默认情况下，采集器保持打开状态并持续读取文件，因为文件处理程序不依赖于文件名。 如果启用close_renamed选项，并且文件被重命名或移动，则文件将不会再次拾取。 Filebeat不会完成读取文件。

close_removed
如果启用此选项，Filebeat会在删除文件时马上关闭harvester。如果一个文件在harvester执行时被提前删除，而您没有启用close_removed，Filebeat会保持文件打开以确保harvester已经完成 通常情况下，文件只能在close_inactive指定的时间内未更新导致文件关闭后才能被删除。 如果此设置导致文件因为太早从磁盘中删除而未完全读取，请禁用此选项。 该选项默认启用。 如果禁用此选项，则还必须禁用clean_removed。
WINDOWS：如果您的Windows日志轮换系统由于无法轮换文件而显示错误，请确保启用此选项。

close_eof
启用此选项后，一旦文件结束，Filebeat会立即关闭文件。 当您的文件只写入一次而不是不时更新时，这很有用。

close_timeout
启用此选项时，Filebeat会为每个harvester提供预定义的使用期限。无论harvester读取到文件中哪个位置，在close_timeout时间过后读数都会停止。当您只想在文件上花费预定义的时间时，此选项可用于较旧的日志文件。虽然close_timeout将在预定义的超时后关闭文件，但如果文件仍在更新中，探矿者将根据定义的scan_frequency再次启动一个新的采集器。此收割机的close_timeout将在超时倒计时后重新开始。此选项在输出被阻止的情况下特别有用，这使得Filebeat即使对从磁盘中删除的文件也保持打开的文件处理程序。将close_timeout设置为5m可确保文件定期关闭，以便操作系统释放它们。如果您将close_timeout设置为与ignore_older相等，则在收割机关闭时如果修改该文件，则该文件将不会被拾取。这些设置的组合通常会导致数据丢失，并且不会发送完整的文件。当您对包含多行事件的日志使用close_timeout时，收割机可能会停在多行事件的中间，这意味着只会发送部分事件。如果收割机再次启动并且文件仍然存在，则只会发送事件的第二部分。该选项默认设置为0，这意味着它被禁用。

二. clean_ *

clean_ *选项用于清理注册表文件中的状态条目。 这些设置有助于减小注册表文件的大小，并可以防止潜在的inode重用问题。

clean_inactive
启用此选项后，Filebeat将在指定的非活动时间段过去后移除文件的状态。如果文件已被Filebeat忽略（该文件比ignore_older早），则只能删除该状态。 clean_inactive设置必须大于ignore_older + scan_frequency，以确保在收集文件时不会删除状态。否则，该设置可能会导致Filebeat不断重新发送全部内容，因为clean_inactive将删除文件的状态，harvester仍然执行，如果文件更新或再次出现，则从头开始读取文件。 clean_inactive配置选项对于减小注册表文件的大小非常有用，特别是在每天生成大量新文件的情况下。此配置选项对于防止Linux上的inode重用导致的Filebeat问题也很有用。

clean_removed
启用此选项后，如果文件在磁盘上找不到，Filebeat会清除注册表中的文件，该选项默认启用。
如果您还禁用了close_removed，则必须禁用此选项。

三. scan_frequency

指定扫描指定路径目录下是否有新的文件产生。例如，指定1以尽可能频繁地扫描目录，而不会导致Filebeat过于频繁地扫描。我们不建议将此值设置为<1秒。
如果您需要近实时发送日志行，请勿使用非常低的scan_frequency，但应调整close_inactive，以便文件处理程序保持打开状态并持续轮询您的文件。
默认设置是10秒。

注意区分backoff

四. harvester_buffer_size

每个harvester在获取文件时使用的缓冲区的大小（以字节为单位）。 默认值是16384。

五. max_bytes

单个日志消息可以拥有的最大字节数。 max_bytes之后的所有字节被丢弃并且不发送。 此设置对于可能变大的多行日志消息特别有用。 默认值是10MB（10485760）。

六. json

这些选项使Filebeat能够解码构造为JSON消息的日志。这些选项使Filebeat解码日志结构化为JSON消息。

解码发生在行过滤和多行之前。 如果您设置了message_key选项，您可以将JSON解码与过滤和多行结合使用。 在应用程序日志被包装在JSON对象中的情况下，这可能会很有用，例如Docker发生的情况。

配置示例：

 json.keys_under_root：true
 json.add_error_key：true
 json.message_key：日志 

您必须至少指定以下设置之一才能启用JSON解析模式：

keys_under_root

默认情况下，解码后的JSON放在输出文档中的“json”键下。 如果启用此设置，则会将键复制到输出文档的顶层。 默认值是false。

overwrite_keys

如果启用了keys_under_root和此设置，则来自解码的JSON对象的值会覆盖Filebeat通常添加的字段（类型，源，偏移量等）以防冲突。

add_error_key

如果启用此设置，则在出现JSON解组错误或配置中定义了message_key但无法使用的情况下，Filebeat会添加“error.message”和“error.type：json”项。

message_key

一个可选的配置设置，用于指定应用行筛选和多行设置的JSON密钥。 如果指定，键必须位于JSON对象的顶层，并且与键关联的值必须是字符串，否则不会发生筛选或多行聚合。

七. multiline

控制Filebeat如何处理跨越多行的日志消息的选项。 有关配置多行选项的更多信息，请参阅管理多行消息 。

八. tail_files

如果此选项设置为true，Filebeat开始在每个文件的末尾读取新文件，而不是开始。 将此选项与日志轮换结合使用时，可能会跳过新文件中的第一个日志条目。 默认设置为false。

此选项适用于Filebeat尚未处理的文件。 如果您之前运行Filebeat并且文件的状态已被tail_files ，则tail_files将不适用。 harvester将继续之前的状态执行扫描。 要将tail_files应用于所有文件，您必须停止Filebeat并删除注册表文件。 请注意，这样做会删除以前的所有状态。

注意
当您首次在一组日志文件上运行Filebeat时，忽略旧的日志。 第一次运行后，我们建议禁用此选项，否则您可能会在文件轮转过程中丢失行。

九. pipeline

为此prespectors生成的事件设置的接收节点管道标识。

注意
管道标识也可以在Elasticsearch输出中进行配置，但此选项通常会让配置文件更简单。 如果管道在prespectors和输出中均配置，则选择prespectors中的配置。

十. fields

向输出的每一条日志添加额外的信息，比如“level:debug”，方便后续对日志进行分组统计。默认情况下，会在输出信息的fields子目录下以指定的新增fields建立子目录。
例如

fields: 
level: debug

则在Kibana看到的内容如下：

十一. fields_under_root

如果该选项设置为true，则新增fields成为顶级目录，而不是将其放在fields目录下。自定义的field会覆盖filebeat默认的field。例如添加如下配置：

fields: 
level: debug 
fields_under_root: true

则在Kibana看到的内容如下：

十二. symlinks

symlinks选项允许Filebeat除了常规文件以外还收集符号链接。 收集符号链接时，Filebeat会打开并读取原始文件。

当您配置收集符号链接时，请确保排除是否存在原始文件路径。 如果单个prespectors配置为收集的符号链接指向的路径已存在同一个prespectors下，则prespectors将检测到问题并仅处理找到的第一个文件。 但是，如果配置了两个不同的prespectors（一个读取符号链接而另一个读取原始路径），则将采集两个路径，导致Filebeat发送重复数据，并且prespectors覆盖彼此的状态。

如果符号链接到日志文件的文件名中包含额外的元数据，并且您想要在Logstash中处理元数据，则symlinks选项可能很有用。 例如Kubernetes日志文件的情况。

由于此选项可能会导致数据丢失，因此默认情况下会禁用它。

十三. backoff

该选项指定达到EOF后再次检查文件是否有更新的间隔时间，默认值是1秒。

十四. max_backoff

该选项指定达到EOF后再次检查文件是否有更新的最大间隔时间。 默认值是10秒。

要求：max_backoff应始终设置为max_backoff <= scan_frequency 。 如果max_backoff应该更大，建议关闭文件处理程序，而不要让探矿者重新拾取文件。

十五. backoff_factor

指定backoff的增长因数，backoff=backoff * backoff_factor <= max_backoff。 默认值是2。

十六. harvester_limit

harvester_limit选项限制一个探矿者并行启动的收割机数量。 这直接关系到打开的文件处理程序的最大数量。 harvester_limit的默认值是0，这意味着没有限制。 如果要采集的文件数量超过操作系统的打开文件处理程序限制，则此配置很有用。

设置收割机数量的限制意味着可能不是所有文件都并行打开。 因此，我们建议您将此选项与close_*选项组合使用，以确保收割机更经常停止，以便可以拾取新文件。

目前，如果新的收割机可以重新启动，收割机将随机挑选。 这意味着收割机可能刚刚关闭，然后再次更新，可能会启动而不是收割机收集长时间未收割的文件。

此配置选项适用于每个探矿者。 您可以使用此选项通过分配更高限的收割机来间接地为某些探矿者设置更高的优先级。

十七. max_message_size

与type: udp ，指定通过UDP接收的消息的最大大小。 默认值是10240。

十八. containers

这些选项仅在使用docker探矿器类型时可用。 它们允许配置容器列表以从中读取日志。

Docker探矿者将在其路径下搜索容器日志，并将其解析为常见的消息行，并提取时间戳。 所有事情都发生在行筛选，多行和JSON解码之前，因此可以与它们结合使用。

配置示例：

  containers.ids：
   - '8b6fe7dc9e067b58476dc57d6986dd96d7100430c5de3b109a99cd56ac655347' 

使用docker探矿者类型时，您必须定义containers.ids ，这些都是可用的设置：

• ids
  必需的，从'*'读取日志的Docker容器ID列表可以用作从所有容器中读取的ID。
• path
  Docker日志所在的基本路径。 缺省值是/var/lib/docker/containers 。
• stream
  只读取给定的流，这可以是： all ， stdout或stderr 。 默认是all 。