filestream 输入

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

1. 对 close.on_state_change.* 选项的检查是在带外进行的。因此，如果输出被阻塞，Filebeat 可以关闭读取器，避免打开过多的文件。
2. 对于所有与 paths 配置匹配的文件，无论 harvester_limit 如何，都可以获得详细的指标。这样，您可以跟踪所有文件，即使是未被主动读取的文件。
3. parsers 的顺序是可配置的。因此，可以解析 JSON 行，然后将内容聚合成一个多行事件。
4. 某些位置更新和元数据更改不再依赖于发布管道。如果管道被阻塞，一些更改仍然会应用于注册表。
5. 只有最新的更新会被序列化到注册表。相比之下，log 输入在收到输出的每个 ACK 时都必须序列化完整的注册表。这使得此输入的注册表更新速度快得多。
6. 输入确保只有偏移量更新被写入注册表仅附加日志。log 会写入完整的文件状态。
7. 过时的条目可以从注册表中删除，即使没有活动的输入。
8. 默认行为是使用 fingerprint file_identity 根据文件内容来识别文件。这解决了由 inode 重用导致的数据重复问题。

要配置此输入，请指定一个基于 glob 的 paths 列表，Filebeat 将抓取这些路径来定位和获取日志行。

示例配置

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 的字段。

fingerprint 是默认推荐的文件标识方法，因为它不依赖文件系统/操作系统，它从文件的一部分（默认前 1024 字节）生成一个哈希值并用它来识别文件。这与移动/重命名文件的日志轮换策略以及在文件标识符可能更易变的 Windows 上配合良好。缺点是 Filebeat 会等待文件达到 1024 字节后才开始摄入任何文件。

有关详细信息，请参阅fingerprint 配置。

选择 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

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

此外，为避免轮换日志消息重复，请勿将 path 方法用于 file_identity。或者使用 exclude_files 选项排除轮换的文件。

prospector 正在运行一个文件系统监视器，它会查找在 paths 选项中指定的文件。目前仅支持简单的文件系统扫描。

此 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 会为在指定路径下找到的每个文件启动一个 harvester。您可以每行指定一个路径。每行以破折号 (-) 开头。

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 检查指定收集路径中新文件的频率。例如，如果您指定一个 glob，如 /var/log/*，则目录会以 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（也用于比较文件）在重启后可能会更改。

配置

Fingerprint 模式默认禁用。

通常，日志行包含时间戳和其他唯一字段，应该能够使用 fingerprint 模式，但在每个用例中，用户都应检查其日志以确定 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 的范围下，则 harvester 将首先完成读取文件，并在达到 close.on_state_change.inactive 后关闭它。然后，在该之后，该文件将被忽略。

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

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

• 从未被收集的文件
• 已收集但自 ignore_inactive 设置的时间以来未更新的文件。

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

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

要从注册表文件中删除先前收集的文件的状态，请使用 clean_inactive 配置选项。

启用 take_over 后，此 filestream 输入将接管来自 log 输入或其他 filestream 输入的状态。仅接管此输入正在主动收集的文件的状态。

要从 log 输入接管文件，只需设置 take_over.enabled: true。

要从其他 filestream 输入接管状态，请设置 take_over.enabled: true，并将 take_over.from_ids 设置为您想要从中迁移文件的现有 filestream ID 列表。

在这两种情况下，请确保您希望此输入接管的文件与 paths 中配置的 glob 匹配。

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

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

1. 省略从 log 输入接管

创建此 take over 模式是为了实现从已弃用的 log 输入平滑迁移到新的 filestream 输入，并允许在不重新摄入数据的情况下更改 filestream 输入 ID。

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

接管只能迁移在 filestream 输入启动期间未被忽略的现有文件的状态。一旦输入开始摄入数据，如果出现新文件，filestream 将不会尝试迁移其状态。

close.* 配置选项用于在达到特定条件或时间后关闭 harvester。关闭 harvester 意味着关闭文件句柄。如果在 harvester 关闭后文件被更新，文件将在 prospector.scanner.check_interval 经过后再次被拾取。但是，如果在 harvester 关闭期间文件被移动或删除，Filebeat 将无法再次拾取该文件，harvester 未读取的任何数据将丢失。

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

启用此选项后，如果文件在指定持续时间未被收集，Filebeat 将关闭文件句柄。定义时期的计数器从 harvester 读取最后一行日志时开始。它不基于文件的修改时间。如果关闭的文件再次更改，将启动新的 harvester，并且在 prospector.scanner.check_interval 经过后，将拾取最新的更改。

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

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

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

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

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

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

WINDOWS：如果您的 Windows 日志轮换系统因为无法轮换文件而显示错误，您应该启用此选项。

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

此选项默认启用。如果您禁用此选项，则还必须禁用 clean_removed。

WINDOWS：如果您的 Windows 日志轮换系统因为无法轮换文件而显示错误，请确保启用此选项。

启用此选项后，一旦到达文件末尾，Filebeat 将关闭文件。当文件仅被写入一次且不时更新时，此选项很有用。例如，当您将每个日志事件写入新文件时，就会发生这种情况。此选项默认禁用。

启用此选项后，Filebeat 会为每个 harvester 提供一个预定的生命周期。无论读取器位于文件的何处，读取都将在 close.reader.after_interval 期限过去后停止。当您只想在旧日志文件上花费预定时间时，此选项会很有用。虽然 close.reader.after_interval 会在预定超时后关闭文件，但如果文件仍在更新，Filebeat 将按照定义的 prospector.scanner.check_interval 再次启动新的 harvester。此 harvester 的 close.reader.after_interval 将再次开始超时倒计时。

当输出被阻塞时，此选项特别有用，这会导致 Filebeat 即使对于已从磁盘删除的文件也保持文件句柄打开。将 close.reader.after_interval 设置为 5m 可确保文件定期关闭，以便操作系统可以释放它们。

如果您将 close.reader.after_interval 设置为等于 ignore_older，则如果文件在 harvester 关闭期间被修改，它将不会被拾取。这种设置组合通常会导致数据丢失，并且不会发送完整的文件。

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

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

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 跳过行。

启用此选项后，如果文件在磁盘上无法再找到其最后已知名称，Filebeat 将从注册表中清除这些文件。这意味着在 harvester 完成后重命名的文件也将被删除。此选项默认启用。

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

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

backoff 选项指定 Filebeat 检查打开文件更新的积极程度。在大多数情况下，您可以使用默认值。

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

Filebeat 在达到 EOF 后，检查文件之前等待的最长时间。在多次延迟检查文件后，等待时间永远不会超过 backoff.max。由于读取新行最多需要 10 秒，因此将 backoff.max 指定为 10 秒意味着，在最坏的情况下，如果 Filebeat 多次延迟，可能会将新行添加到日志文件。默认值为 10s。

要求：将 backoff.max 设置为大于或等于 backoff.init，且小于或等于 prospector.scanner.check_interval (backoff.init <= backoff.max <= prospector.scanner.check_interval)。如果 backoff.max 需要更高，建议改为关闭文件句柄，让 Filebeat 再次拾取文件。

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

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

目前，如果可以再次启动新的 harvester，则会随机选择 harvester。这意味着可能启动刚刚关闭后又再次更新的文件的 harvester，而不是长时间未被收集的文件的 harvester。

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

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

请遵循此全面指南，了解如何选择适合您的用例的文件标识选项。

fingerprint

Filebeat 的默认行为是通过对特定范围（默认为 0 到 1024 字节）进行哈希处理，基于内容来识别文件。

有关详细信息，请参阅fingerprint 配置。

file_identity.fingerprint: ~

native

使用文件的 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

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

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

默认情况下，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
---

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

有效编码

• plain：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, 拉丁语-1
• iso8859-2：ISO8859-2, 拉丁语-2
• iso8859-3：ISO8859-3, 拉丁语-3
• iso8859-4：ISO8859-4, 拉丁语-4
• iso8859-5：ISO8859-5, 拉丁语/西里尔语
• iso8859-6：ISO8859-6, 拉丁语/阿拉伯语
• iso8859-7：ISO8859-7, 拉丁语/希腊语
• iso8859-8：ISO8859-8, 拉丁语/希伯来语
• iso8859-9：ISO8859-9, 拉丁语-5
• iso8859-10：ISO8859-10, 拉丁语-6
• iso8859-13：ISO8859-13, 拉丁语-7
• iso8859-14：ISO8859-14, 拉丁语-8
• iso8859-15：ISO8859-15, 拉丁语-9
• iso8859-16：ISO8859-16, 拉丁语-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 西里尔语编码
• 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 编码是特殊的，因为它不对任何输入进行验证或转换。

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。

单个日志消息可以拥有的最大字节数。超过 message_max_bytes 的所有字节都将被丢弃，不予发送。默认值为 10MB (10485760)。

此选项需要一个解析器列表，日志行必须经过这些解析器进行处理。

可用解析器

• 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 中的点，并将它们扩展为分层对象结构。例如，{"a.b.c": 123} 将扩展为 {"a":{"b":{"c":123}}}。当输入由ECS 日志记录器产生时，应启用此设置。

add_error_key

如果启用此设置，在发生 JSON 解组错误或配置中定义了 message_key 但无法使用时，Filebeat 将添加 "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 格式的 syslog 消息。

支持的配置选项包括

format

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

timezone

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

log_errors

（可选）如果为 true，解析器将记录 syslog 解析错误。默认值为 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"]

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

注意

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

使用 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 子字典下。如果自定义字段名与 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。