« Logstash 配置文件 用于安全设置的密钥库 »
Elastic 文档 ›Logstash 参考 [8.14] ›设置和运行 Logstash

logstash.yml

编辑

logstash.yml编辑

您可以在 Logstash 设置文件 logstash.yml 中设置选项来控制 Logstash 的执行。例如，您可以指定管道设置、配置文件的位置、日志记录选项和其他设置。当您运行 Logstash 时，logstash.yml 文件中的大多数设置也可以作为 命令行标志 使用。您在命令行设置的任何标志都会覆盖 logstash.yml 文件中的相应设置。

logstash.yml 文件是用 YAML 编写的。它的位置因平台而异（请参阅 Logstash 目录布局）。您可以以分层形式指定设置，也可以使用扁平键。例如，要使用分层形式设置管道批处理大小和批处理延迟，您可以指定

pipeline:
  batch:
    size: 125
    delay: 50

要将相同的值表示为扁平键，您可以指定

pipeline.batch.size: 125
pipeline.batch.delay: 50

logstash.yml 文件还支持在设置值中使用 bash 风格的环境变量和密钥库密钥插值。

pipeline:
  batch:
    size: ${BATCH_SIZE}
    delay: ${BATCH_DELAY:50}
node:
  name: "node_${LS_NODE_NAME}"
path:
   queue: "/tmp/${QUEUE_DIR:queue}"

请注意，支持 ${VAR_NAME:default_value} 表示法，在上面的示例中设置默认批处理延迟为 50，默认 path.queue 为 /tmp/queue。

模块也可以在 logstash.yml 文件中指定。模块定义将采用以下格式

modules:
  - name: MODULE_NAME1
    var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
    var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE
    var.PLUGIN_TYPE2.PLUGIN_NAME2.KEY1: VALUE
    var.PLUGIN_TYPE3.PLUGIN_NAME3.KEY1: VALUE
  - name: MODULE_NAME2
    var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY1: VALUE
    var.PLUGIN_TYPE1.PLUGIN_NAME1.KEY2: VALUE

如果使用了 命令行标志 --modules，则 logstash.yml 文件中定义的任何模块都将被忽略。

logstash.yml 文件包含以下设置。

设置 描述 默认值

node.name

节点的描述性名称。

机器的主机名

path.data

Logstash 及其插件用于任何持久性需求的目录。

LOGSTASH_HOME/data

pipeline.id

管道的 ID。

main

pipeline.workers

将并行执行管道的过滤器和输出阶段的工作线程数。如果 pipelines.yml 中的 pipeline.workers 或 logstash.yml 中的 pipeline.workers 未覆盖此设置，则此设置使用 java.lang.Runtime.getRuntime.availableProcessors 值作为默认值。如果您修改了此设置并发现事件正在备份，或者 CPU 未饱和，请考虑增加此数字以更好地利用机器处理能力。

主机 CPU 内核数

pipeline.batch.size

单个工作线程在尝试执行其过滤器和输出之前从输入收集的最大事件数。较大的批处理大小通常效率更高，但会增加内存开销。您可能需要在 jvm.options 配置文件中增加 JVM 堆空间。有关更多信息，请参阅 Logstash 配置文件。

125

pipeline.batch.delay

创建管道事件批处理时，在将尺寸过小的批处理分派给管道工作线程之前，每个事件等待的毫秒数。

50

pipeline.unsafe_shutdown

设置为 true 时，即使内存中仍有正在进行的事件，也会强制 Logstash 在关闭期间退出。默认情况下，Logstash 将拒绝退出，直到所有接收到的事件都已推送到输出。启用此选项可能会导致关闭期间数据丢失。

false

pipeline.plugin_classloaders

（测试版）在独立的类加载器中加载 Java 插件以隔离其依赖项。

false

pipeline.ordered

设置管道事件排序。有效选项为

  • auto。如果 pipeline.workers 设置为 1，则自动启用排序，否则禁用排序。
  • true。对管道强制执行排序，如果有多个工作线程，则阻止 Logstash 启动。
  • false。禁用保留顺序所需的处理。不保证排序，但您可以节省保留顺序的处理成本。

auto

pipeline.ecs_compatibility

设置管道的 ecs_compatibility 默认值，该设置可用于实现 ECS 兼容模式的插件，以便与 Elastic Common Schema 一起使用。可能的值为

  • disabled
  • v1
  • v8

此选项允许在插件中 提前选择加入（或预先选择退出）ECS 兼容性 模式，计划在未来 Logstash 的主要版本中默认启用。

disabled 以外的值目前被视为测试版，在升级 Logstash 时可能会产生意外后果。

disabled

path.config

主管道的 Logstash 配置的路径。如果指定目录或通配符，则按字母顺序从目录中读取配置文件。

特定于平台。请参阅 Logstash 目录布局。

config.string

包含要用于主管道的管道配置的字符串。使用与配置文件相同的语法。

不适用

config.test_and_exit

设置为 true 时，检查配置是否有效，然后退出。请注意，此设置不会检查 grok 模式的正确性。Logstash 可以从目录中读取多个配置文件。如果将此设置与 log.level: debug 结合使用，Logstash 将记录组合的配置文件，并使用源文件注释每个配置块。

false

config.reload.automatic

设置为 true 时，定期检查配置是否已更改，并在配置更改时重新加载配置。这也可以通过 SIGHUP 信号手动触发。

false

config.reload.interval

Logstash 检查配置文件更改的频率（以秒为单位）。请注意，需要单位限定符（s）。

3s

config.debug

设置为 true 时，将显示完全编译的配置作为调试日志消息。您还必须设置 log.level: debug。警告：日志消息将包含作为明文传递给插件配置的任何 *密码* 选项，并且可能会导致明文密码出现在您的日志中！

false

config.support_escapes

设置为 true 时，带引号的字符串将处理以下转义序列：\n 变为文字换行符（ASCII 10）。\r 变为文字回车符（ASCII 13）。\t 变为文字制表符（ASCII 9）。\\ 变为文字反斜杠 \。\" 变为文字双引号。\' 变为文字单引号。

false

config.field_reference.escape_style

提供了一种引用包含 字段引用特殊字符 [ 和 ] 的字段的方法。

此功能处于 技术预览版 中，将来可能会发生变化。

当前选项为

  • percent：URI 风格的 %+HH 十六进制编码的 UTF-8 字节（[ → %5B；] → %5D）
  • ampersand：HTML 风格的 &#+DD+; 编码的十进制 Unicode 代码点（[ → [；] → ]）
  • none：*不能* 引用包含特殊字符的字段名称。

none

modules

配置后，modules 必须位于此表上方描述的嵌套 YAML 结构中。

不适用

queue.type

用于事件缓冲的内部队列模型。为传统的基于内存的队列指定 memory，为基于磁盘的已确认队列指定 persisted（持久队列）。

memory

path.queue

启用持久队列（queue.type: persisted）时存储数据文件的目录路径。

path.data/queue

queue.page_capacity

启用持久队列（queue.type: persisted）时使用的页面数据文件的大小。队列数据由追加式数据文件组成，这些文件分为多个页面。

64mb

queue.max_events

启用持久队列（queue.type: persisted）时队列中未读事件的最大数量。

0（无限制）

queue.max_bytes

队列的总容量（queue.type: persisted），以字节数为单位。确保磁盘驱动器的容量大于您在此处指定的值。如果同时指定了 queue.max_events 和 queue.max_bytes，则 Logstash 使用先达到哪个条件。

1024mb (1g)

queue.checkpoint.acks

启用持久队列（queue.type: persisted）时，在强制执行检查点之前已确认的事件的最大数量。指定 queue.checkpoint.acks: 0 可将此值设置为无限制。

1024

queue.checkpoint.writes

启用持久队列（queue.type: persisted）时，在强制执行检查点之前写入的事件的最大数量。指定 queue.checkpoint.writes: 0 可将此值设置为无限制。

1024

queue.checkpoint.retry

启用后，对于任何失败的检查点写入，Logstash 将在每次尝试的检查点写入中重试四次。任何后续错误都不会重试。这是针对仅在 Windows 平台、具有非标准行为的文件系统（如 SAN）上出现的失败检查点写入的解决方法，除非在这些特定情况下，否则不建议这样做。（queue.type: persisted）

true

queue.drain

启用后，Logstash 会等到持久队列（queue.type: persisted）清空后再关闭。

false

dead_letter_queue.enable

指示 Logstash 启用插件支持的 DLQ 功能的标志。

false

dead_letter_queue.max_bytes

每个死信队列的最大大小。如果条目会使死信队列的大小超过此设置，则将删除这些条目。

1024mb

dead_letter_queue.storage_policy

定义在达到 dead_letter_queue.max_bytes 设置时要执行的操作：drop_newer 停止接受会导致文件大小超过限制的新值，drop_older 删除最旧的事件以为新事件腾出空间。

drop_newer

path.dead_letter_queue

存储死信队列数据文件的目录路径。

path.data/dead_letter_queue

api.enabled

默认情况下启用 HTTP API。可以禁用它，但依赖它的功能将无法按预期工作。

true

api.environment

API 返回提供的字符串作为其响应的一部分。设置您的环境可能有助于区分生产环境和测试环境中名称相似的节点。

production

api.http.host

HTTP API 端点的绑定地址。默认情况下，Logstash HTTP API 仅绑定到本地环回接口。如果安全配置（api.ssl.enabled: true 和 api.auth.type: basic），HTTP API 将绑定到*所有*可用接口。

"127.0.0.1"

api.http.port

HTTP API 端点的绑定端口。

9600-9700

api.ssl.enabled

设置为 true 以在 HTTP API 上启用 SSL。这样做需要同时设置 api.ssl.keystore.path 和 api.ssl.keystore.password。

false

api.ssl.keystore.path

用于保护 Logstash API 的有效 JKS 或 PKCS12 密钥库的路径。密钥库必须受密码保护，并且必须包含单个证书链和一个私钥。除非将 api.ssl.enabled 设置为 true，否则将忽略此设置。

不适用

api.ssl.keystore.password

使用 api.ssl.keystore.path 提供的密钥库的密码。除非将 api.ssl.enabled 设置为 true，否则将忽略此设置。

不适用

api.ssl.supported_protocols

建立安全连接时允许使用的 SSL/TLS 版本列表。协议的可用性取决于 JVM 版本。默认情况下禁用某些协议，需要通过更改 $JDK_HOME/conf/security/java.security 配置文件中的 jdk.tls.disabledAlgorithms 来手动启用。可能的值为

  • TLSv1
  • TLSv1.1
  • TLSv1.2
  • TLSv1.3

不适用

api.auth.type

设置为 basic 以使用 api.auth.basic.username 和 api.auth.basic.password 提供的凭据在 API 上要求 HTTP 基本身份验证。

none

api.auth.basic.username

HTTP 基本身份验证所需的用户名。除非将 api.auth.type 设置为 basic，否则将忽略。

不适用

api.auth.basic.password

HTTP 基本身份验证所需的密码。除非将 api.auth.type 设置为 basic，否则将忽略。它应该符合默认的密码策略，该策略要求非空且至少包含 8 个字符的字符串，其中包括一个数字、一个大写字母和一个小写字母。可以通过以下选项自定义默认密码策略

  • 将 api.auth.basic.password_policy.include.digit 设置为 REQUIRED（默认值）以仅接受包含至少一个数字的密码，或设置为 OPTIONAL 以从要求中排除。
  • 将 api.auth.basic.password_policy.include.upper 设置为 REQUIRED（默认值）以仅接受包含至少一个大写字母的密码，或设置为 OPTIONAL 以从要求中排除。
  • 将 api.auth.basic.password_policy.include.lower 设置为 REQUIRED（默认值）以仅接受包含至少一个小写字母的密码，或设置为 OPTIONAL 以从要求中排除。
  • 将 api.auth.basic.password_policy.include.symbol 设置为 REQUIRED 以仅接受包含至少一个特殊字符的密码，或设置为 OPTIONAL（默认值）以从要求中排除。
  • 如果希望密码长度超过 8 个字符的默认设置，请将 api.auth.basic.password_policy.length.minimum 设置为 9 到 1024 之间的值。

不适用

api.auth.basic.password_policy.mode

当不满足密码要求时，会引发 WARN 或 ERROR 消息。除非将 api.auth.type 设置为 basic，否则将忽略。

WARN

log.level

日志级别。有效选项包括

  • fatal
  • error
  • warn
  • info
  • debug
  • trace

info

log.format

日志格式。设置为 json 以 JSON 格式记录日志，或设置为 plain 以使用 Object#.inspect。

plain

log.format.json.fix_duplicate_message_fields

当日志格式为 json 时，避免日志行中字段名称的冲突。

false

path.logs

Logstash 将日志写入到的目录。

LOGSTASH_HOME/logs

pipeline.separate_logs

这是一个布尔值设置，用于在不同日志文件中启用按管道分离日志。如果启用，Logstash 将为每个管道创建一个不同的日志文件，使用 pipeline.id 作为文件名。目标目录取自 `path.logs` 设置。当 Logstash 中配置了许多管道时，如果您需要排查单个管道中发生的情况，而不受其他管道的干扰，则按管道分离每个日志行可能会有所帮助。

false

path.plugins

在哪里可以找到自定义插件。您可以多次指定此设置以包含多个路径。插件应位于特定的目录层次结构中：PATH/logstash/TYPE/NAME.rb，其中 TYPE 为 inputs、filters、outputs 或 codecs，而 NAME 是插件的名称。

特定于平台。请参阅 Logstash 目录布局。

allow_superuser

设置为 true 以允许或 false 以阻止以超级用户身份运行 Logstash。

true

event_api.tags.illegal

设置为 warn 时，允许向保留的 tags 字段分配非法值。设置为 rename 时，无法使用 tags 中的非法值创建 Logstash 事件。此值将被移动到 _tags，并添加 _tagsparsefailure 标记以指示非法操作。使用非法值执行 set 操作将引发异常。将此标志设置为 warn 已弃用，并将在未来版本中删除。

rename

pipeline.buffer.type

确定在何处为利用内存缓冲区的插件分配内存缓冲区。默认为 direct，可以选择切换到 heap 以选择 Java 堆空间。

direct
« Logstash 配置文件 用于安全设置的密钥库 »