« Logstash 配置文件 用于安全设置的密钥库 »
Elastic 文档 ›Logstash 参考 [8.16] ›设置和运行 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

将并行执行管道过滤器和输出阶段的工作进程数。此设置使用 java.lang.Runtime.getRuntime.availableProcessors 值作为默认值，除非被 pipelines.yml 中的 pipeline.workers 或 logstash.yml 中的 pipeline.workers 覆盖。如果您修改了此设置，并且发现事件正在积压，或者 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 的默认值，这是一个可用于实现 ECS 兼容模式的插件的设置，用于与 Elastic Common Schema 一起使用。可能的值为

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

none

modules

如果配置了 modules，则必须采用此表上方描述的嵌套 YAML 结构。

N/A

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

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.auth.basic.username 和 api.auth.basic.password 提供的凭据在 API 上要求 HTTP 基本身份验证。

none

api.auth.basic.username

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

N/A

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 之间的值。

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