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

logstash.yml

编辑

logstash.yml

编辑

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

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

false

pipeline.ordered

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

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

auto

pipeline.ecs_compatibility

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

  • disabled
  • v1
  • v8

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

除 disabled 之外的值目前被认为是 BETA 版，并且在升级 Logstash 时可能会产生意想不到的后果。

disabled

path.config

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

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

config.string

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

N/A

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：UTF-8 字节的 URI 样式 %+HH 十六进制编码 ([ → %5B；] → %5D)
  • ampersand：HTML 样式 &#+DD+; 十进制 Unicode 代码点的编码 ([ → [；] → ])
  • none：不能引用包含特殊字符的字段名称。

none

modules

配置时，modules 必须采用此表上面描述的嵌套 YAML 结构。

N/A

queue.type

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

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，否则将忽略此设置。

N/A

api.ssl.keystore.password

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

N/A

api.ssl.supported_protocols

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

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

N/A

api.auth.type

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

none

api.auth.basic.username

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

N/A

api.auth.basic.password

HTTP Basic 身份验证所需的密码。除非 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 之间的值。

N/A

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.log`s 设置。当 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 配置文件 用于安全设置的密钥库 »