filestream 输入

使用 filestream 输入从日志文件中读取行。它是 log 输入的改进替代方案。它对现有输入进行了各种改进

• 默认行为是使用 fingerprint file_identity 根据文件内容识别文件。这解决了由 inode 重用引起的数据重复问题。
• close.on_state_change.* 选项的验证是带外进行的。如果输出被阻塞，Filebeat 可以关闭读取器，以避免保持打开过多的文件。
• 所有匹配 paths 配置的文件都可以获得详细指标，无论 harvester_limit 如何设置。通过这种方式，您可以跟踪所有文件，甚至包括那些未被活跃读取的文件。
• parsers 的顺序是可配置的。您可以先解析 JSON 行，然后将内容聚合成多行事件。
• 某些位置更新和元数据更改不再依赖于发布管道。如果管道被阻塞，某些更改仍会应用到注册表中。
• 只有最近的更新会被序列化到注册表中。相比之下，log 输入必须在每次收到来自输出的 ACK 时序列化完整的注册表。这使得使用此输入的注册表更新速度快得多。
• 此输入确保只有偏移量更新被写入注册表的仅追加日志中。而 log 会写入完整的文件状态。
• 即使没有活动的输入，也可以从注册表中删除陈旧的条目。
• 作为一个 Beta 功能，它可以读取 GZIP 文件。

要配置此输入，请指定一个基于 glob 的 paths 列表，这些路径必须被爬取以定位并获取日志行。

配置示例

filebeat.inputs:
- type: filestream
  id: my-filestream-id
  paths:
    - /var/log/messages
    - /var/log/*.log
		

您可以对从这些文件中采集的行应用额外的 配置设置（如 fields、include_lines、exclude_lines 等）。您指定的选项将应用于此输入采集的所有文件。

要对不同的文件应用不同的配置设置，您需要定义多个输入部分

filebeat.inputs:
- type: filestream
  id: my-filestream-id
  paths:
    - /var/log/system.log
    - /var/log/wifi.log
- type: filestream
  id: apache-filestream-id
  paths:
    - "/var/log/apache2/*"
  fields:
    apache: true
		

1. 从两个文件采集行：system.log 和 wifi.log。
2. 采集 apache2 目录中每个文件的行，并使用 fields 配置选项在输出中添加一个名为 apache 的字段。

filestream 输入可以摄取 GZIP 文件。GZIP 文件会被像处理其他任何文件一样对待，并享有 filestream 提供的相同保证。这包括偏移量跟踪和从部分读取的文件中恢复。

Filestream 在读取数据时会在内存中解压 GZIP 文件。它遵循 buffer_size，最多读取 buffer_size 大小的解压数据。

要启用它，请将 compression 设置为 auto。有关更多详细信息，请参阅 compression。

filebeat.inputs:
  - type: filestream
    id: "test-filestream"
    paths:
      - /var/some-app/app.log*
    compression: auto
		

读取 GZIP 文件需要将 file_identity 设置为 fingerprint，这是默认行为。

指纹识别是在解压后的数据上进行的，并且日志轮转会自动处理。

GZIP 文件被视为不可变的，这意味着 filestream 不期望有新数据追加到其中。一旦到达文件末尾，采集器（harvester）就会关闭，并且 filestream 不会尝试摄取新数据。

然而，filestream 可以正确处理在 GZIP 文件仍在写入磁盘时开始读取的情况。在这种情况下，filestream 将读取文件直到成功到达末尾。当数据完全解压、读取到 GZIP 页脚且大小和校验和验证均通过时，即视为到达文件末尾。如果验证失败，filestream 会记录错误并将文件视为已完全读取。

我们的基准测试表明，读取 GZIP 文件对 Filebeat 的吞吐量及其 CPU 使用率的影响微乎其微。

但是，每个读取 GZIP 文件的采集器会消耗大约 100KB 的额外内存。在配置 harvester_limit 时，应考虑此内存增量。

在处理文件轮转时，请避免采集符号链接。相反，应使用 paths 设置指向原始文件，并指定一个匹配您要采集的文件及其所有已轮转文件的模式。同时，确保您的日志轮转策略能防止消息丢失或重复。有关详细信息，请参阅 日志轮转导致事件丢失或重复。

此外，为了避免轮转日志消息重复，请不要在 file_identity 中使用 path 方法。或者通过 exclude_files 选项排除已轮转的文件。

由于日志文件不断被写入，必须对其进行轮转和清除，以防止记录器应用程序填满磁盘。轮转是由外部应用程序完成的，因此，Filebeat 需要知道如何与其配合的信息。

从轮转文件读取时，请确保路径配置包含活动文件和所有轮转后的文件。

默认情况下，Filebeat 能够在以下策略中正确跟踪文件

• create：轮转时创建一个具有唯一名称的新活动文件
• rename：轮转后的文件被重命名

但是，在使用 copytruncate 策略的情况下，您应该为 Filebeat 提供额外的配置。

如果日志轮转应用程序复制活动文件的内容然后截断原始文件，请使用这些选项帮助 Filebeat 正确读取文件。

设置 suffix_regex 选项，以便 Filebeat 能够区分活动文件和轮转后的文件。输入中支持两种后缀类型：数值和日期。

如果您的轮转文件在文件名末尾附加了递增索引，例如：活动文件为 apache.log，轮转后的文件名为 apache.log.1、apache.log.2 等，请使用以下配置。

---
rotation.external.strategy.copytruncate:
  suffix_regex: \.\d$
---
		

如果轮转日期附加在文件名末尾，例如：活动文件为 apache.log，轮转后的文件名为 apache.log-20210526、apache.log-20210527 等，请使用以下配置

---
rotation.external.strategy.copytruncate:
  suffix_regex: \-\d{6}$
  dateformat: -20060102
---
		

fingerprint 是默认且推荐的文件标识方式，因为它不依赖于文件系统/操作系统；它通过文件的一部分（默认前 1024 字节）生成哈希值，并以此识别文件。这对于移动/重命名文件的日志轮转策略以及在文件标识符可能更不稳定的 Windows 上都非常有效。缺点是 Filebeat 会等待文件达到 1024 字节后才开始摄取。

请参阅 指纹配置了解详情。

选择 path 会指示 Filebeat 根据路径识别文件。如果 inode 和设备 ID 可能发生变化，这是避免重复读取文件的一种快速方法。但请记住，如果文件被轮转（重命名），它们将被重新读取并重新提交。

如果即使设备 ID 发生变化而 inode 保持不变，可以使用 inode_marker 选项。在这种情况下，如果可能，您应该选择此方法而不是 path。您必须配置一个 Filebeat 可读的标记文件，并在 inode_marker 的 path 选项中设置其路径。

该文件的内容对于设备必须是唯一的。您可以放入存储输入的设备或挂载点的 UUID。以下单行示例为所选挂载点 /logs 生成一个隐藏的标记文件：请注意，不应在 Windows 上使用此选项，因为文件标识符可能更不稳定。

$ lsblk -o MOUNTPOINT,UUID | grep /logs | awk '{print $2}' >> /logs/.filebeat-marker
		

要将生成的文件设置为 file_identity 的标记，您应该按以下方式配置输入

filebeat.inputs:
- type: filestream
  id: my-filestream-id
  paths:
    - /logs/*.log
  file_identity.inode_marker.path: /logs/.filebeat-marker
		

默认情况下，Filestream 输入不会删除文件。如果开启该选项，当满足以下条件时，Filestream 输入可以删除文件

• 读取器已关闭。默认不活动时间为 5 分钟。
• 已到达文件末尾 (EOF)。
• 所有事件都已由输出确认。

如果还有待确认的事件，或者在删除文件时出现问题，采集器将在下一次扫描时重新打开，并重试删除操作。您可以通过设置 prospector.scanner.check_interval 属性来配置文件的更改扫描频率。

输出始终确认已成功写入的事件。不过，它也会确认被丢弃的事件。每个输出丢弃事件的条件各不相同。详情请参阅 输出 文档。

如果 Filebeat 删除文件失败，它会以 2 秒的固定间隔重试最多 5 次。如果所有尝试都失败，采集器将被关闭，并在下一次扫描中启动新的采集器。

如果您开启了删除文件功能，请保持 clean_removed 处于启用状态。删除文件功能默认处于关闭状态。

设置为 true 时，当满足以下条件时文件将被移除

• 读取器已关闭。
• 已到达文件末尾 (EOF)。
• 所有事件都已由输出确认。

在读取器关闭且所有事件都已确认之后，在尝试移除文件之前等待的时间间隔。

在等待宽限期期间，该文件的采集器保持打开状态。如果文件大小在等待宽限期期间发生变化，则采集器关闭并从头开始重新开始。宽限期到期后，Filestream 会检查文件是否位于 EOF。如果不是，则采集器关闭，否则将文件移除。在宽限期期间，Filebeat 会根据 prospector 的相同间隔（由 prospector.scanner.check_interval 配置）定期检查文件更改。默认值为 30 分钟。

有关如何使用此功能的示例，请参阅 在摄取后移除文件。

此 filestream 输入的唯一标识符。每个 filestream 输入必须具有唯一的 ID。Filestream 不会启动 ID 重复的输入。

这允许 Filebeat 运行具有相同 ID 的多个 filestream 输入实例。这是为了增加与 9.0 之前行为的向后兼容性。它默认为 false 且在新的配置中不建议使用。

此设置按输入应用，因此请确保在所有使用重复 ID 的 filestream 输入中都启用它。

将被爬取和获取的基于 glob 的路径列表。此处还支持 Go Glob 支持的所有模式。例如，要从预定义级别的子目录中获取所有文件，可以使用以下模式：/var/log/*/*.log。这将从 /var/log 的子文件夹中获取所有 .log 文件。它不会从 /var/log 文件夹本身获取日志文件。可以使用可选的 recursive_glob 设置递归地获取目录中所有子目录的所有文件。

Filebeat 为在指定路径下找到的每个文件启动一个采集器。您可以每行指定一个路径。每行以破折号 (-) 开头。

启用 take_over 时，此 filestream 输入将接管来自 log 输入或其他 filestream 输入的状态。只有该输入正在活跃采集的文件的状态才会被接管。

启用接管模式的语法随版本变化

• 使用 take_over.enabled: true。
• 使用 take_over: true。

要从 log 输入接管文件，请启用接管模式，并确保您希望此输入接管的文件匹配 paths 中配置的 glob 模式。

take_over:
  enabled: true
		

take_over: true
		

要从其他 filestream 输入接管状态，请启用接管模式，将 take_over.from_ids 设置为您希望从中迁移文件的现有 filestream ID 列表，并确保您希望此输入接管的文件匹配 paths 中配置的 glob 模式。

当设置 take_over.from_ids 时，不会从 log 输入接管文件。迁移仅限于 filestream 输入。

take_over:
  enabled: true
  from_ids: ["foo", "bar"]
		

此接管模式旨在实现从已弃用的 log 输入向新 filestream 输入的平滑迁移，并允许在不重新摄取数据的情况下更改 filestream 输入 ID。

有关迁移过程的更多详细信息，请参阅 将 log 输入配置迁移到 filestream。

使用接管模式时，请注意以下几点

• 只有在源（被接管的）输入不再处于活动状态时，接管模式才能正常工作。如果源输入仍在采集正在迁移的文件，将导致数据重复，在某些情况下可能会导致数据丢失。
• 使用 take_over.enabled: true 需要 filestream 具有唯一的 ID。
• 接管只能迁移在 filestream 输入启动期间未被忽略的现有文件中的状态。一旦输入开始摄取数据，如果有新文件出现，filestream 将不会尝试迁移其状态。

可以配置不同的 file_identity 方法，以适应收集日志消息的环境。

按照 这份全面指南 了解如何选择适合您用例的文件标识方式选项。

在 9.x 中，扫描器指纹识别默认启用。当您显式配置非指纹 file_identity（例如 native、path 或 inode_marker）且未显式设置 prospector.scanner.fingerprint.enabled 时，Filebeat 会自动禁用该输入的扫描器指纹识别。

fingerprint

Filebeat 的默认行为是通过哈希处理特定范围（默认为 0 到 1024 字节）根据内容识别文件。

请参阅 指纹配置了解详情。

file_identity.fingerprint: ~
		

native

使用文件的 inode 和设备 ID 区分文件。这是 9.0.0 之前版本 Filebeat 中的默认文件标识方式。

在某些情况下，inode 和设备 ID 的值在文件的生命周期内可能会发生变化。例如，使用 Linux LVM（逻辑卷管理）时，设备号是在模块加载时动态分配的（请参阅 Red Hat Enterprise Linux 文档中的 持久设备号）。为了在这种情况下避免数据重复的可能性，您可以将 file_identity 设置为 fingerprint 而不是 native。

由 native 文件标识生成的文件状态可以迁移到 fingerprint。

file_identity.native: ~
		

path

要基于文件的路径来标识文件，请使用此策略。

警告

仅当您的日志文件轮转到输入范围之外的文件夹或根本不轮转时，才使用此策略。否则，您最终会得到重复事件。

警告

该策略不支持重命名文件。如果输入文件被重命名，且新路径与输入设置匹配，则 Filebeat 将重新读取它。

由 path 文件标识生成的文件状态可以迁移到 fingerprint。

file_identity.path: ~
		

inode_marker

如果设备 ID 不时变化，您必须使用此方法来区分文件。Windows 不支持此选项。

按照以下方式设置标记文件的位置

file_identity.inode_marker.path: /logs/.filebeat-marker
		

close.* 配置选项用于在满足特定标准或时间后关闭采集器。关闭采集器意味着关闭文件句柄。如果文件在采集器关闭后更新，文件将在 prospector.scanner.check_interval 耗尽后再次被识别。但是，如果文件在采集器关闭期间被移动或删除，Filebeat 将无法再次识别该文件，并且采集器尚未读取的任何数据都将丢失。

close.on_state_change.* 设置异步应用于从文件读取，这意味着如果 Filebeat 由于输出阻塞、队列已满或其他问题处于阻塞状态，文件无论如何都会被关闭。

启用此选项后，如果文件在指定的持续时间内未被采集，Filebeat 会关闭文件句柄。定义期限的计时器从采集器读取最后一行日志开始。它不是基于文件的修改时间。如果关闭的文件再次发生变化，将启动一个新的采集器，最新的变化将在 prospector.scanner.check_interval 耗尽后被拾取。

我们建议您将 close.on_state_change.inactive 设置为一个大于日志文件更新频率最小值的值。例如，如果您的日志文件每隔几秒钟更新一次，您可以安全地将 close.on_state_change.inactive 设置为 1m。如果有更新率差异很大的日志文件，您可以使用多个具有不同值的配置。

将 close.on_state_change.inactive 设置为较低的值意味着文件句柄会更快关闭。然而，这有一个副作用，即如果采集器关闭，新的日志行将不会近乎实时地发送。

关闭文件的时间戳并不取决于文件的修改时间。相反，Filebeat 使用反映文件最后一次被采集时间的内部时间戳。例如，如果 close.on_state_change.inactive 设置为 5 分钟，则 5 分钟的倒计时从采集器读取文件最后一行之后开始。

您可以使用诸如 2h（2 小时）和 5m（5 分钟）之类的时间字符串。默认值为 5m。

启用此选项后，Filebeat 会在重命名文件时关闭文件句柄。例如，在轮转文件时会发生这种情况。默认情况下，采集器保持打开状态并继续读取文件，因为文件句柄不依赖于文件名。如果启用了 close.on_state_change.renamed 选项，并且文件被重命名或移动，从而不再与指定的模式匹配，则该文件将不会再次被拾取。Filebeat 不会完成文件的读取。

配置了基于 path 的 file_identity 时不要使用此选项。启用该选项没有意义，因为 Filebeat 无法使用路径名作为唯一标识符来检测重命名。

WINDOWS: 如果您的 Windows 日志轮转系统由于无法轮转文件而显示错误，您应该启用此选项。

启用此选项后，Filebeat 会在文件被移除时关闭采集器。通常，文件仅应在 close.on_state_change.inactive 指定的持续时间内处于不活动状态后才被移除。但是，如果文件过早移除且您未启用 close.on_state_change.removed，Filebeat 会保持文件打开状态以确保采集器已完成。如果此设置导致文件由于过早从磁盘移除而未完全读取，请禁用此选项。

此选项在 Windows 上默认启用，在所有其他操作系统上默认禁用。

启用此选项后，Filebeat 将在到达文件末尾后立即关闭文件。这在文件仅写入一次且不会不时更新的情况下很有用。例如，当您将每个日志事件写入一个新文件时。默认情况下此选项处于禁用状态。

启用此选项后，Filebeat 为每个采集器提供一个预定义的生命周期。无论读取器在文件中的什么位置，读取都会在 close.reader.after_interval 期限届满后停止。当您只想在旧日志文件上花费预定义的时间量时，此选项非常有用。虽然 close.reader.after_interval 将在预定义的超时后关闭文件，但如果文件仍在更新中，Filebeat 将根据定义的 prospector.scanner.check_interval 再次启动一个新的采集器。并且此采集器的 close.reader.after_interval 将再次从超时倒计时开始。

此选项在输出阻塞的情况下特别有用，这会导致 Filebeat 甚至为已从磁盘删除的文件也保留打开的文件句柄。将 close.reader.after_interval 设置为 5m 可确保周期性关闭文件，以便操作系统可以释放它们。

如果您将 close.reader.after_interval 设置为等于 ignore_older，则当采集器关闭时，如果文件被修改，将不会被发现。这种设置组合通常会导致数据丢失，并且无法发送完整的文件。

当您将 close.reader.after_interval 用于包含多行事件的日志时，采集器可能会在多行事件中间停止，这意味着只有部分事件会被发送。如果采集器再次启动且文件仍然存在，则只发送事件的第二部分。

此选项默认设置为 0，表示已禁用。

当 read_until_eof.enabled 为 true 且在输入正在读取文件时收到关机信号时，输入将继续读取直到 EOF 或 read_until_eof.timeout 届满，而不是立即停止。关机信号可能来自 Filebeat 重新加载其配置（例如，当 Kubernetes pod 终止时 autodiscover 提供者移除输入）或来自取消输入的任何其他路径。

如果不使用此选项，在仍在读取文件时停止的输入会留下未读取的字节。使用此选项，采集器读取到 EOF，然后才退出。

read_until_eof.enabled 默认为 true，且 read_until_eof.timeout 默认为 1m。超时必须大于零。

要保留之前的行为并使输入在取消时立即退出，请设置

- type: filestream
  id: my-filestream-id
  paths:
    - /var/log/some-app/*.log
  read_until_eof:
    enabled: false
		

要自定义超时，请设置 read_until_eof.timeout

- type: filestream
  id: my-filestream-id
  paths:
    - /var/log/some-app/*.log
  read_until_eof:
    enabled: true
    timeout: 30s
		

此选项与 close.* 选项协同工作。在输入排空至 EOF 期间，针对该文件的状态更改检查 (close.on_state_change.removed, close.on_state_change.renamed) 和 close.reader.after_interval 均会被挂起，因此它们无法切断排空过程。一旦文件读取完毕（或触发超时），输入将正常关闭。

此选项不会更改 Filebeat 的事件交付保证。该保证位于输入级别：在打开的文件上仍有可读字节时，输入不会退出。

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

启用此选项后，Filebeat 会在指定的非活动周期届满后移除文件状态。仅当文件已被 Filebeat 忽略（文件早于 ignore_older）时，状态才可以移除。clean_inactive 设置必须大于 ignore_older + prospector.scanner.check_interval，以确保在文件仍在采集时不会移除任何状态。否则，该设置可能会导致 Filebeat 不断重发全文，因为 clean_inactive 移除了仍由 Filebeat 检测到的文件的状态。如果文件再次更新或出现，文件将从头开始读取。

clean_inactive 配置选项对于减小注册表文件的大小非常有用，尤其是在每天产生大量新文件的情况下。

此配置选项也可用于防止由 Linux 上的 inode 重用引起的 Filebeat 问题。有关详细信息，请参阅 Inode 重用导致 Filebeat 跳过行。

要禁用，请将 clean_inactive 设置为

• -1 (推荐)
• 0
  警告

  在早期版本中，设置 clean_inactive: 0 会导致 Filebeat 在重启时重新摄取所有文件。

Filebeat 通过在 clean_inactive <= ignore_older + prospector.scanner.check_interval 或禁用 ignore_older 时启动失败来强制执行限制。要恢复不强制执行配置限制并在 clean_inactive: 0 时重新摄取文件的旧行为，请设置 legacy_clean_inactive: true。

您可以使用 5m（5 分钟）、2h45m（2 小时 45 分钟）、48h 等时间字符串。有效的时间单位为 "ns"、"us" (或 "µs")、"ms"、"s"、"m"、"h"。默认值为 -1。

启用此选项后，如果无法再在磁盘上以最后已知的名称找到文件，Filebeat 将从注册表中清理该文件。这意味着在采集完成后被重命名的文件也将被移除。默认情况下启用此选项。

如果共享驱动器消失很短时间后再次出现，所有文件都将从头再次读取，因为状态已从注册表文件中移除。在这种情况，我们建议您禁用 clean_removed 选项。

如果您还禁用了 close.on_state_change.removed，则必须禁用此选项。

退避选项指定了 Filebeat 爬取打开的文件进行更新的激进程度。在大多数情况下，您可以使用默认值。

backoff.init 选项定义了 Filebeat 在到达 EOF 后第一次等待多长时间再次检查文件。退避间隔以指数方式增加。默认值为 2s。因此，文件将在 2 秒后检查，然后 4 秒，然后 8 秒，依此类推，直到达到 backoff.max 定义的限制。每当文件中出现新行时，backoff.init 值都会重置为初始值。

到达 EOF 后 Filebeat 再次检查文件的最大等待时间。在多次退避检查文件后，等待时间永远不会超过 backoff.max。因为读取新行最多需要 10s，为 backoff.max 指定 10s 意味着在最坏的情况下，如果 Filebeat 多次退避，可能会向日志文件添加一个新行。默认值为 10s。

要求：设置 backoff.max 大于或等于 backoff.init 且小于或等于 prospector.scanner.check_interval (backoff.init <= backoff.max <= prospector.scanner.check_interval)。如果 backoff.max 需要更高，建议关闭文件句柄让 Filebeat 重新发现该文件。

harvester_limit 选项限制为一个输入并行启动的采集器数量。这直接关系到打开的文件句柄的最大数量。harvester_limit 的默认值为 0，表示没有限制。如果待采集的文件数量超过操作系统的打开文件句柄限制，此配置很有用。

对采集器数量设置限制意味着可能并非所有文件都会并行打开。因此，我们建议您将此选项与 close.on_state_change.* 选项结合使用，以确保采集器更频繁地停止，从而可以发现新文件。

目前，如果可以再次启动一个新的采集器，采集器是随机选择的。这意味着，一个刚被关闭且随后更新的文件，其采集器有可能被启动，而不是启动一个长时间未被采集的文件的采集器。

此配置选项适用于每个输入。您可以通过分配更高的采集器限制，间接为某些输入设置更高的优先级。

将日志文件所有者包含到 log.file 元数据中。Windows 不支持此选项。

将日志文件组包含到 log.file 元数据中。Windows 不支持此选项。

Filebeat 要排除的匹配行的正则表达式列表。Filebeat 会丢弃匹配列表中任何正则表达式的行。默认情况下不丢弃任何行。空行将被忽略。

以下示例配置 Filebeat 丢弃任何以 DBG 开头的行。

filebeat.inputs:
- type: filestream
  ...
  exclude_lines: ['^DBG']
		

参阅 正则表达式支持 了解支持的正则表达式模式列表。

Filebeat 要包含的匹配行的正则表达式列表。Filebeat 仅导出匹配列表中任何正则表达式的行。默认情况下导出所有行。空行将被忽略。

以下示例配置 Filebeat 导出任何以 ERR 或 WARN 开头的行

filebeat.inputs:
- type: filestream
  ...
  include_lines: ['^ERR', '^WARN']
		

以下示例导出所有包含 sometext 的日志行，除了以 DBG 开头的行（调试消息）

filebeat.inputs:
- type: filestream
  ...
  include_lines: ['sometext']
  exclude_lines: ['^DBG']
		

参阅 正则表达式支持 了解支持的正则表达式模式列表。

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

指定如何处理文件压缩。有效值为

""（空字符串或未设置）

禁用压缩处理。所有文件都被视为纯文本。这是默认设置。

gzip

将所有文件视为 GZIP 压缩。当您知道所有匹配 paths 的文件都是 GZIP 文件时，请使用此项。

auto

自动检测 GZIP 文件。将检查文件的 GZIP 魔法字节，且解压缩仅应用于实际的 GZIP 文件。纯文本文件被正常读取。

filebeat.inputs:
  - type: filestream
    id: "my-filestream"
    paths:
      - /var/log/app/*.log*
    compression: auto
		

有关 GZIP 支持的更多详细信息，请参阅 读取 GZIP 文件。

设置为 true 时，启用带自动检测的 GZIP 文件读取。

单条日志消息可以拥有的最大字节数。message_max_bytes 之后的所有字节将被丢弃且不会发送。默认值为 10MB (10485760)。

指定输入文件中用于分隔行的字符。默认值为 auto。

有效值

• auto：自动检测 LF 和 CR+LF 换行符（U+000A 和 U+000D U+000A）。
• line_feed：换行 (LF, \n, U+000A)。
• vertical_tab：垂直制表符 (VT, \v, U+000B)。
• form_feed：换页 (FF, \f, U+000C)。
• carriage_return：回车 (CR, \r, U+000D)。
• carriage_return_line_feed：回车后跟换行 (CR+LF, \r\n, U+000D U+000A)。
• next_line：下一行 (NEL, U+0085)。
• line_separator：行分隔符 (LS, U+2028)。
• paragraph_separator：段落分隔符 (PS, U+2029)。
• null_terminator：空字符 (\u0000, U+0000)。

此选项预期一个日志行必须通过的解析器列表。

可用解析器

• multiline
• ndjson
• container
• syslog
• include_message

在此示例中，Filebeat 正在读取由 3 行组成并封装在单行 JSON 对象中的多行消息。多行消息存储在键 msg 下。

filebeat.inputs:
- type: filestream
  ...
  parsers:
    - ndjson:
        target: ""
        message_key: msg
    - multiline:
        type: count
        count_lines: 3
		

详情请参阅下面可用的解析器设置。

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

这些选项使得 Filebeat 能够解码结构化为 JSON 消息的日志。Filebeat 按行处理日志，因此仅当每条消息包含一个 JSON 对象时 JSON 解码才有效。

解码发生在行过滤之前。如果您设置了 message_key 选项，则可以将 JSON 解码与过滤相结合。这在应用程序日志封装在 JSON 对象中（如使用 Docker 时）的情况下很有用。

配置示例

- ndjson:
    target: ""
    add_error_key: true
    message_key: log
		

target

应该包含已解析键值对的新 JSON 对象的名称。如果将其留空，新键将放在根目录下。

overwrite_keys

在发生冲突时，来自已解码 JSON 对象的值覆盖 Filebeat 通常添加的字段（type、source、offset 等）。如果要保留之前添加的值，请将其禁用。

expand_keys

如果启用此设置，Filebeat 将递归地对解码 JSON 中的键进行去点号（de-dot）处理，并将其扩展为层次对象结构。例如，{"a.b.c": 123} 将被扩展为 {"a":{"b":{"c":123}}}。当输入由 ECS logger 产生时，应启用此设置。

add_error_key

如果启用此设置，Filebeat 会在发生 JSON 反序列化错误或配置中定义了 message_key 但无法使用时添加 "error.message" 和 "error.type: json" 键。

message_key

一个可选的配置设置，指定对其应用行过滤和多行设置的 JSON 键。如果指定了此键，该键必须在 JSON 对象的顶层，且与该键关联的值必须是字符串，否则不会发生过滤或多行聚合。

document_id

可选配置设置，指定用于设置文档 ID 的 JSON 键。如果配置，该字段将从原始 JSON 文档中移除并存储在 @metadata._id 中

ignore_decoding_error

一个可选的配置设置，指定是否应记录 JSON 解码错误。如果设置为 true，则不记录错误。默认值为 false。

使用 container 解析器从容器日志文件中提取信息。它将行解析为普通消息行，同时提取时间戳。

stream

仅从指定的流中读取：all、stdout 或 stderr。默认值为 all。

format

解析日志时使用给定的格式：auto、docker 或 cri。默认值为 auto，它会自动检测格式。要禁用自动检测，请设置任何其他选项。

以下代码片段配置 Filebeat 读取默认 Kubernetes 日志路径下所有容器的 stdout 流

paths:
  - "/var/log/containers/*.log"
parsers:
  - container:
      stream: stdout
		

syslog 解析器解析 RFC 3164 和/或 RFC 5424 格式的系统日志消息。

支持的配置选项为

format

（可选）要使用的系统日志格式，rfc3164 或 rfc5424。要从日志条目中自动检测格式，请将此选项设置为 auto。默认值为 auto。

timezone

（可选）IANA 时区名称（例如 America/New York）或固定时间偏移量（例如 +0200），用于在解析不含时区的 syslog 时间戳时使用。可以指定 Local 以使用机器的本地时区。默认值为 Local。

log_errors

（可选）如果为 true，解析器将记录系统日志解析错误。默认值为 false。

add_error_key

（可选）如果启用此设置，解析器会将遇到的解析错误添加或附加到 error.message 键中。默认值为 true。

配置示例

- syslog:
    format: rfc3164
    timezone: America/Chicago
    log_errors: true
    add_error_key: true
		

时间戳

RFC 3164 格式接受以下形式的时间戳

• 本地时间戳 (Mmm dd hh:mm:ss)

  • Jan 23 14:09:01

• RFC-3339*

  • 2003-10-11T22:14:15Z
  • 2003-10-11T22:14:15.123456Z
  • 2003-10-11T22:14:15-06:00
  • 2003-10-11T22:14:15.123456-06:00

注意：随 RFC 3164 消息而来的本地时间戳（例如 Jan 23 14:09:01）缺乏年份和时区信息。将使用 timezone 配置选项丰富时区，并将使用 Filebeat 系统的本地时间（考虑时区）丰富年份。正因如此，消息可能会出现在未来的时间里。一个可能发生这种情况的例子是在 2021 年 12 月 31 日产生的日志在 2022 年 1 月 1 日被摄取。日志将被丰富为 2022 年而非 2021 年。

RFC 5424 格式接受以下形式的时间戳

• RFC-3339

  • 2003-10-11T22:14:15Z
  • 2003-10-11T22:14:15.123456Z
  • 2003-10-11T22:14:15-06:00
  • 2003-10-11T22:14:15.123456-06:00

标有星号 (*) 的格式是非标准容许形式。

在解析器管道中使用 include_message 解析器来过滤消息。匹配所提供模式的消息会被传递给下一个解析器，其他消息则被丢弃。

如果您想控制过滤发生的时机，应使用 include_message 而不是 include_lines。include_lines 在解析器之后运行，include_message 在解析器管道中运行。

patterns

要匹配的正则表达式模式列表。

此示例向您展示如何包含以字符串 ERR 或 WARN 开头的消息

paths:
  - "/var/log/containers/*.log"
parsers:
  - include_message.patterns: ["^ERR", "^WARN"]
		

用于读取包含国际字符的数据的文件编码。参阅 W3C 推荐在 HTML5 中使用的编码名称。

有效编码

• plain：纯 ASCII 编码
• utf-8 或 utf8：UTF-8 编码
• gbk：简体中文
• iso8859-6e：ISO8859-6E，拉丁/阿拉伯语
• iso8859-6i：ISO8859-6I，拉丁/阿拉伯语
• iso8859-8e：ISO8859-8E，拉丁/希伯来语
• iso8859-8i：ISO8859-8I，拉丁/希伯来语
• iso8859-1：ISO8859-1，Latin-1
• iso8859-2：ISO8859-2，Latin-2
• iso8859-3：ISO8859-3，Latin-3
• iso8859-4：ISO8859-4，Latin-4
• iso8859-5：ISO8859-5，拉丁/西里尔语
• iso8859-6：ISO8859-6，拉丁/阿拉伯语
• iso8859-7：ISO8859-7，拉丁/希腊语
• iso8859-8：ISO8859-8，拉丁/希伯来语
• iso8859-9：ISO8859-9，Latin-5
• iso8859-10：ISO8859-10，Latin-6
• iso8859-13：ISO8859-13，Latin-7
• iso8859-14：ISO8859-14，Latin-8
• iso8859-15：ISO8859-15，Latin-9
• iso8859-16：ISO8859-16，Latin-10
• cp437：IBM CodePage 437
• cp850：IBM CodePage 850
• cp852：IBM CodePage 852
• cp855：IBM CodePage 855
• cp858：IBM CodePage 858
• cp860：IBM CodePage 860
• cp862：IBM CodePage 862
• cp863：IBM CodePage 863
• cp865：IBM CodePage 865
• cp866：IBM CodePage 866
• ebcdic-037：IBM CodePage 037
• ebcdic-1040：IBM CodePage 1140
• ebcdic-1047：IBM CodePage 1047
• koi8r：KOI8-R，俄语 (西里尔语)
• koi8u：KOI8-U，乌克兰语 (西里尔语)
• macintosh：Macintosh 编码
• macintosh-cyrillic：Macintosh Cyrillic 编码
• windows1250：Windows1250，中欧和东欧
• windows1251：Windows1251，俄语、塞尔维亚语 (西里尔语)
• windows1252：Windows1252，旧版
• windows1253：Windows1253，现代希腊语
• windows1254：Windows1254，土耳其语
• windows1255：Windows1255，希伯来语
• windows1256：Windows1256，阿拉伯语
• windows1257：Windows1257，爱沙尼亚语、拉脱维亚语、立陶宛语
• windows1258：Windows1258，越南语
• windows874：Windows874，ISO/IEC 8859-11，拉丁语/泰语
• utf-16-bom：带必须 BOM 的 UTF-16
• utf-16be-bom：带必须 BOM 的大端序 UTF-16
• utf-16le-bom：带必须 BOM 的小端序 UTF-16

plain 编码很特殊，因为它不校验或转换任何输入。

prospector 正在运行一个文件系统监听程序，它会在 paths 选项指定的路径中寻找文件。目前仅支持简单的文件系统扫描。

scanner 监听配置的路径。它周期性地扫描文件系统并将文件系统事件返回给 Prospector。

启用将 ** 扩展为递归 glob 模式的功能。启用此功能后，每个路径中最右侧的 ** 会被扩展为固定数量的 glob 模式。例如：/foo/** 会扩展为 /foo、/foo/*、/foo/*/* 等。如果启用，它将单个 ** 扩展为 8 层深的 * 模式。

此功能默认启用。将 prospector.scanner.recursive_glob 设置为 false 可将其禁用。

Filebeat 要忽略的匹配文件的正则表达式列表。默认不排除任何文件。

以下示例配置 Filebeat 忽略所有具有 gz 扩展名的文件

filebeat.inputs:
- type: filestream
  ...
  prospector.scanner.exclude_files: ['\.gz$']
		

参阅 正则表达式支持 了解支持的正则表达式模式列表。

Filebeat 要包含的匹配文件的正则表达式列表。如果提供了正则表达式列表，则仅采集符合模式允许的文件。

默认不排除任何文件。此选项是 prospector.scanner.exclude_files 的对应部分。

以下示例配置 Filebeat 排除不在 /var/log 下的文件

filebeat.inputs:
- type: filestream
  ...
  prospector.scanner.include_files: ['^/var/log/.*']
		

参阅 正则表达式支持 了解支持的正则表达式模式列表。

symlinks 选项允许 Filebeat 除了普通文件外还采集符号链接。在采集符号链接时，Filebeat 即使报告的是符号链接的路径，也会打开并读取原始文件。

当您配置采集符号链接时，请确保排除了原始路径。如果一个输入同时被配置为采集符号链接和原始文件，Filebeat 会检测到该问题，并只处理发现的第一个文件。但是，如果配置了两个不同的输入（一个读取符号链接，另一个读取原始路径），则两个路径都将被采集，导致 Filebeat 发送重复数据，且输入会相互覆盖对方的状态。

如果日志文件的符号链接在文件名中包含额外的元数据，且您希望在 Logstash 中处理这些元数据，那么 symlinks 选项可能会很有用。例如，Kubernetes 日志文件就是这种情况。

因为此选项可能导致数据丢失，它默认处于禁用状态。

如果启用此选项，若文件大小未变但修改时间已变为比之前更晚的时间，则该文件将被重发。默认禁用，以避免意外重发文件。

Filebeat 检查为采集指定的路径中新文件的频率。例如，如果您指定了像 /var/log/* 这样的 glob，目录会以 check_interval 指定的频率进行文件扫描。指定 1s 以在不引起 Filebeat 扫描过频的情况下尽可能快地扫描。我们不建议将此值设置为 <1s。

如果您要求日志行近乎实时地发送，不要使用极低的 check_interval，而应调整 close.on_state_change.inactive，以便文件句柄保持打开并不断轮询您的文件。

默认设置为 10s。

在比较文件时，不依赖设备 ID 和 inode 值，而是比较文件给定字节范围的哈希值。这是 Filebeat 的默认行为。

以下是可能发生这种情况的一些场景

1. 某些文件系统（如在 Docker 中）缓存并重用 inode

   例如，如果您：

   1. 创建一个文件 (touch x)

   2. 查看该文件的 inode (ls -i x)

   3. 删除该文件 (rm x)

   4. 立刻创建一个新文件 (touch y)

   5. 查看新文件的 inode (ls -i y)

      对于这两个文件，即使它们文件名不同，您也可能会看到相同的 inode 值。

2. 非 Ext 文件系统可能会更改 inode

   Ext 文件系统将 inode 号码存储在 i_ino 文件中，位于磁盘写入的 inode 结构体内。在这种情况下，如果文件是同一个（不是另一个同名文件），则保证其 inode 号码是相同的。

   如果文件系统不是 Ext，则 inode 号码是由文件系统驱动程序定义的 inode 操作生成的。由于它们没有 inode 的概念，它们必须模仿 inode 的所有内部字段以符合 VFS，因此这个号码在重启后可能会不同，甚至在关闭并重新打开文件后（理论上）也是如此。

3. 某些文件处理工具会更改 inode 值

   有时用户由于使用 rsync 或 sed 等工具而不经意地更改了 inode。

4. 某些操作系统在重启后会更改设备 ID

   根据挂载方式，（同样用于比较文件的）设备 ID 可能会在重启后发生变化。

配置

通常，日志行包含时间戳和其他唯一字段，它们应该能够使用指纹模式。但在任何用例中，用户都应检查其日志以确定 offset 和 length 参数的适当值。默认的 offset 是 0，默认的 length 是 1024 或 1 KB。length 不能小于 64。

fingerprint:
  enabled: false
  offset: 0
  length: 1024
		

启用此选项后，Filebeat 将忽略在指定时间跨度之前修改的任何文件。如果您长期保留日志文件，配置 ignore_older 会特别有用。例如，如果您想启动 Filebeat 但只想发送最新的文件和上周的文件，您可以配置此选项。

您可以使用诸如 2h（2 小时）和 5m（5 分钟）的时间字符串。默认值为 0，表示禁用该设置。注释掉配置与将其设置为 0 效果相同。

受此设置影响的文件分为两类

• 从未采集过的文件
• 已采集过但超过 ignore_older 时间未更新的文件

对于从未见过的文件，偏移量状态被设置为文件末尾。如果状态已存在，偏移量将被重置为文件大小。如果文件稍后再次更新，则在设置的偏移量位置继续读取。

ignore_older 设置依赖于文件的修改时间来决定是否忽略文件。如果写入行时文件的修改时间没有更新（在 Windows 上可能发生），ignore_older 设置可能会导致 Filebeat 即使在稍后添加了内容也忽略该文件。

要从注册表文件中移除之前已采集文件的状态，请使用 clean_inactive 配置选项。

在一个文件被 Filebeat 忽略之前，必须先将其关闭。为确保一个文件在被忽略时不再处于采集状态，您必须将 ignore_older 设置为比 close.on_state_change.inactive 更长的时间。

如果当前正在采集的一个文件落入 ignore_older 范围内，采集器将首先完成该文件的读取，并在达到 close.on_state_change.inactive 后将其关闭。在那之后，该文件才会被忽略。

如果启用此选项，Filebeat 将忽略自所选时间以来未更新的所有文件。可能的选项是 since_first_start 和 since_last_start。第一个选项忽略自 Filebeat 第一次启动以来未更新的所有文件。当 Beat 可能因配置更改或故障而重新启动时，它很有用。第二个选项告诉 Beat 读取自其启动以来已更新的文件。

受此设置影响的文件分为两类

• 从未采集过的文件
• 已被采集但在 ignore_inactive 之后未更新的文件。

对于以前从未见过的文件，偏移状态设置为文件末尾。如果状态已经存在，偏移量不会改变。如果文件稍后再次更新，阅读将在设定的偏移位置继续。

该设置依靠文件的修改时间来决定是否忽略文件。如果在向文件写入行时文件的修改时间没有更新（这可能发生在 Windows 上），该设置可能会导致 Filebeat 忽略文件，即使稍后添加了内容。

要从注册表文件中移除之前已采集文件的状态，请使用 clean_inactive 配置选项。

所有输入均支持以下配置选项。

使用 enabled 选项启用或禁用输入。默认情况下，enabled 设置为 true。

Filebeat 包含在每个已发布事件的 tags 字段中的标签列表。标签使得在 Kibana 中选择特定事件或在 Logstash 中应用条件过滤变得简单。这些标签将被追加到通用配置中指定的标签列表中。

示例

filebeat.inputs:
- type: filestream
  . . .
  tags: ["json"]
		

可指定的可选字段，用于向输出添加额外信息。例如，您可以添加可用于过滤日志数据的字段。字段可以是标量值、数组、字典或这些形式的任何嵌套组合。默认情况下，您在此处指定的字段将分组在输出文档中的 fields 子字典下。要将自定义字段存储为顶级字段，请将 fields_under_root 选项设置为 true。如果在通用配置中声明了重复字段，则其值将被此处声明的值覆盖。

filebeat.inputs:
- type: filestream
  . . .
  fields:
    app_id: query_engine_12
		

如果此选项设置为 true，则自定义的 fields 存储为输出文档中的顶层字段，而不是归类在 fields 子字典下。如果自定义字段名称与 Filebeat 添加的其他字段名称冲突，则自定义字段将覆盖其他字段。

应用于输入数据的处理器列表。

有关在配置中指定处理器的信息，请参阅处理器。

为此输入生成的事件设置的摄入管道 ID。

如果此选项设置为 true，包含 null 值的字段将发布在输出文档中。默认情况下，keep_null 设置为 false。

如果存在，此格式化字符串将覆盖来自此输入的事件的索引（针对 elasticsearch 输出），或设置事件元数据的 raw_index 字段（针对其他输出）。此字符串只能引用代理名称、版本以及事件时间戳；要访问动态字段，请使用 output.elasticsearch.index 或处理器。

示例值："%{[agent.name]}-myindex-%{+yyyy.MM.dd}" 可能会展开为 "filebeat-myindex-2019.11.01"。

默认情况下，所有事件都包含 host.name。可以将此选项设置为 true，以禁用向所有事件添加此字段。默认值为 false。

此输入通过 HTTP 监控端点 暴露指标。这些指标在 /inputs 路径下暴露。它们可以用于观察输入的活动。请注意，不包括来自处理器的指标。

注：列出的每个指标都有一个对应的 gzip_* 副本（例如 gzip_files_opened_total、gzip_messages_read_total）。这些副本跟踪相同的数据，但专门针对 GZIP 压缩文件。原始指标提供总计数，包括普通文件和 GZIP 文件。