Logstash配置详解

一、配置文件

文件	描述
logstash.yml	配置Logstash的yml。
pipelines.yml	包含在单个Logstash实例中运行多个管道的框架和说明。
jvm.options	配置Logstash的JVM，使用此文件设置总堆空间的初始值和最大值，此文件中的所有其他设置都被视为专家设置。
log4j2.properties	包含log4j 2库的默认设置。

二、配置参数

（一）logstash.yml配置

Logstash配置选项可以控制Logstash的执行。如：指定管道设置、配置文件位置、日志记录选项等。运行Logstash时，大多数配置可以命令行中指定，并覆盖文件的相关配置。

配置	描述	默认值
node.name	节点的名称。	计算机的主机名
path.data	Logstash及其插件用于任何持久需求的目录。	LOGSTASH_HOME/data
pipeline.id	管道的ID。	main
pipeline.workers	设置output或filter插件的工作线程数。	主机cpu数
pipeline.batch.size	单个工作线程从输入收集的最大事件数。	125
pipeline.batch.delay	创建管道事件批处理时，在将较小的批处理发送给管道工作人员之前，等待每个事件的时间（毫秒）。	50
pipeline.unsafe_shutdown	logstash在关闭时，默认会等到所有被处理的event都通过output输出后再执行关闭操作；如果设置为true，则允许强制关闭，而不必等待event处理完毕，此时可能会丢失数据。	false
pipeline.plugin_classloaders	在独立的类加载器中加载Java插件以隔离它们的依赖项。	false
pipeline.ordered	设置管道事件顺序。有效选项包括： auto-如果是管道，则自动启用排序。workers设置为1，否则禁用。 true-在管道上强制排序，如果有多个工作线程则阻止Logstash启动。 false-禁用保持顺序所需的处理。	auto
pipeline.ecs_compatibility	为ecs_compatibility设置管道的默认值，该设置可用于实现ecs兼容模式的插件，以便与Elastic Common Schema一起使用。	disabled
path.config	Logstash的配置路径。	LOGSTASH_HOME/config
config.string	用于主管道的管道配置的字符串。	N/A
config.test_and_exit	设置为true时，检查配置是否有效，然后退出。请注意，使用此设置不会检查grok模式的正确性。Logstash可以从一个目录中读取多个配置文件。如果将此设置与日志相结合。level:debug，Logstash将记录组合的配置文件，并用源文件注释每个配置块。	false
config.reload.automatic	当设置为true时，定期检查配置是否已更改，并在更改时重新加载配置。这也可以通过SIGHUP信号手动触发。	false
config.reload.interval	Logstash检查配置文件更改的频率（以秒为单位）。请注意，单元限定符是必需的。	3s
config.debug	设置为true时，将完全编译的配置显示为调试日志消息。还必须设置日志。级别：调试。警告：日志消息将包括以明文形式传递给插件配置的任何密码选项，并可能导致明文密码出现在日志中！	false
config.support_escapes	当设置为true时，带引号的字符串将处理以下转义序列：\n成为文字换行符（ASCII 10）。\r变成文字回车符（ASCII 13）。\t变为文字选项卡（ASCII 9）。\\变成文字反斜杠\\“变为文字双引号。\'变为文字引号。	false
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 (unlimited)
queue.max_bytes	队列的总容（queue.type:persisted）（字节数）。	1024mb (1g)
queue.checkpoint.acks	启用持久队列时，强制检查点之前确认的最大事件数（queue.type：persisted）。指定queue.checkpoint。acks:0将此值设置为无限制。	1024
queue.checkpoint.writes	启用持久队列时，在强制检查点之前写入的最大事件数（queue.type：persisted）。指定queue.checkpoint。写入：0以将此值设置为无限制。	1024
queue.checkpoint.retry	启用后，对于任何失败的检查点写入，Logstash将在每次尝试检查点写入时重试四次。不会重试任何后续错误。对于只有在Windows平台、具有非标准行为（如SAN）的文件系统上才能看到的失败的检查点写入，这是一种解决方法，除非在这些特定情况下，否则不建议使用。（queue.type：持久化）	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时要执行的操作。达到maxbytes设置：dropnewer停止接受会使文件大小超过限制的新值，dropolder删除最旧的事件，为新事件腾出空间。	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。路径和api.ssl.keystore。要设置的密码。	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.auth.type	设置为basic以要求使用随API.auth.basic.username和API.auth.basic.password提供的凭据在API上进行HTTP basic身份验证。	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。较低的REQUIRED（默认）只接受包含至少一个小写字母的密码，或OPTIONAL（可选）不接受要求。 设置api.auth.basic.password_policy.include。symbol REQUIRED只接受包含至少一个特殊字符的密码，或OPTIONAL（默认）不接受要求。 设置api.auth.basic.password_policy.length。如果希望密码的默认设置超过8个字符，则最小值为9到1024。	N/A
api.auth.basic.password_policy.mode	当不满足密码要求时，引发WARN或ERROR消息。	WARN
log.level	日志级别。有效选项包括： fatal error warn info debug trace	info
log.format	日志格式。设置为json以json格式登录，或设置为plain以使用Object#.inspect。	plain
path.logs	Logstash将其日志写入的目录。	LOGSTASH_HOME/logs
pipeline.separate_logs	这是一个布尔设置，用于在不同的日志文件中按管道分隔日志。如果启用，Logstash将使用管道为每个管道创建不同的日志文件。id作为文件名。目标目录取自`path。日志设置。当Logstash中配置了许多管道时，如果您需要对单个管道中发生的情况进行故障排除，而不受其他管道的干扰，那么将每个管道中的日志行分开可能会很有帮助。	false
path.plugins	插件路径。
allow_superuser	设置为true允许或false阻止以超级用户身份运行Logstash。	true

（二）管道配置

Logstash管道通常有三个阶段：输入→ 过滤器→ 输出。输入生成事件，过滤器修改它们，输出将它们发送到其他地方。

input {
  ...
}

filter {
  ...
}

output {
  ...
}

每个部分都包含一个或多个插件的配置选项。如果指定了多个过滤器，则会按照它们在配置文件中的显示顺序应用它们。如果指定多个输出，事件将按其在配置文件中出现的顺序依次发送到每个目标。

当您准备好在本地机器之外部署管道时，使用pipeline.id设置将管道配置文件添加到logstash.yml存储。当您准备部署多个管道时，请在pipelines.yml中设置和配置。

（三）高级配置

1.多管道配置

如果需要在同一个进程中运行多个管道，通过配置pipelines.yml文件来处理，必须放在path.settings文件夹中。并遵循以下结构：

# config/pipelines.yml
- pipeline.id: my-pipeline_1
  path.config: "/etc/path/to/p1.config"
  pipeline.workers: 3
- pipeline.id: my-other-pipeline
  path.config: "/etc/different/path/p2.cfg"
  queue.type: persisted

该示例显示了两个不同的管道，它们有ID和配置路径描述。对于第一条管道，pipeline.workers设置为3，而在另一个中，启用持久队列功能。未在pipelines.yml文件中明确设置的值将回退到logstash.yml文件中指定的默认值。

如果当前的配置中的事件流不共享相同的输入/过滤器和输出，并且使用标签和条件相互分隔，则使用多个管道特别有用。
在单个实例中具有多个管道还可以使这些事件流具有不同的性能和持久性参数（例如，工作线程数和持久队列的不同设置）。

持久队列和死信队列是按管道隔离的，它们的位置由pipeline.id值命名。

2.管道到管道的通信

使用Logstash的多管道功能时，您可能希望在同一个Logstash实例中连接多个管道。此配置可用于隔离这些管道的执行，以及帮助分解复杂管道的逻辑。管道输入/输出支持本文档后面讨论的许多高级架构模式。

如果需要设置Logstash实例之间的通信，请使用Logstash到Logstash通信或中间队列，如Kafka或Redis。

# config/pipelines.yml
- pipeline.id: beats-server
  config.string: |
    input { beats { port => 5044 } }
    output {
        if [type] == apache {
          pipeline { send_to => weblogs }
        } else if [type] == system {
          pipeline { send_to => syslog }
        } else {
          pipeline { send_to => fallback }
        }
    }
- pipeline.id: weblog-processing
  config.string: |
    input { pipeline { address => weblogs } }
    filter {
       # Weblog filter statements here...
    }
    output {
      elasticsearch { hosts => [es_cluster_a_host] }
    }
- pipeline.id: syslog-processing
  config.string: |
    input { pipeline { address => syslog } }
    filter {
       # Syslog filter statements here...
    }
    output {
      elasticsearch { hosts => [es_cluster_b_host] }
    }
- pipeline.id: fallback-processing
    config.string: |
    input { pipeline { address => fallback } }
    output { elasticsearch { hosts => [es_cluster_b_host] } }

管道输入充当侦听本地进程中单个虚拟地址的虚拟服务器。只有在同一本地Logstash上运行的管道输出才能将事件发送到此地址。管道输出可以将事件发送到虚拟地址列表。如果下游管道被阻塞或不可用，则管道输出将被阻塞。

当事件通过管道发送时，它们的数据被完全复制。对下游管道中事件的修改不会影响任何上游管道中的事件。

管道插件可能是管道之间通信的最有效方式，但它仍然会带来性能成本。Logstash必须在Java堆上为每个下游管道完全复制每个事件。使用此功能可能会影响Logstash的堆内存利用率。

3.重新加载配置文件

您可以设置Logstash以自动检测和重新加载配置更改。

要启用自动配置重新加载，请使用-config.reload启动Logstash。指定了automatic（或-r）命令行选项。例如：

bin/logstash -f apache.config --config.reload.automatic

如果没有开启自动重新加载（--config.reload.automatic），可以强制Logstash重新加载配置文件并重新启动管道。

kill -SIGHUP 14175

14175是运行Logstash的进程的ID。

4.管道多行事件

（1）将Java堆栈跟踪合并到单个事件中

Java堆栈跟踪由多行组成，每行位于初始行之后，以空格开头，如本例所示：

Exception in thread "main" java.lang.NullPointerException
        at com.example.myproject.Book.getTitle(Book.java:16)
        at com.example.myproject.Author.getBookTitles(Author.java:25)
        at com.example.myproject.Bootstrap.main(Bootstrap.java:14)

要将这些行合并到Logstash中的单个事件中，请对多行编解码器使用以下配置：

input {
  stdin {
    codec => multiline {
      pattern => "^\s"
      what => "previous"
    }
  }
}

（2）将C-style的行延续合并到单个事件中

一些编程语言使用行尾的\字符表示该行继续，如本例所示：

printf ("%10.10ld  \t %10.10ld \t %s\
  %f", w, x, y, z );

要将这些行合并到Logstash中的单个事件中，请对多行编解码器使用以下配置：

input {
  stdin {
    codec => multiline {
      pattern => "\\$"
      what => "next"
    }
  }
}

此配置将以空格开头的任何行合并到前一行。

（3）合并时间戳事件的多行

Elasticsearch等服务的活动日志通常以时间戳开头，后跟特定活动的信息，如本例所示：

[2015-08-24 11:49:14,389][INFO ][env                      ] [Letha] using [1] data paths, mounts [[/
(/dev/disk1)]], net usable_space [34.5gb], net total_space [118.9gb], types [hfs]

要将这些行合并到Logstash中的单个事件中，请对多行编解码器使用以下配置：

input {
  file {
    path => "/var/log/someapp.log"
    codec => multiline {
      pattern => "^%{TIMESTAMP_ISO8601} "
      negate => true
      what => previous
    }
  }
}

此配置使用否定选项指定任何不以时间戳开头的行都属于前一行。

5.集中式管道管理配置

#设置为true可为Logstash启用X-Pack集中式配置管理。
xpack.management.enabled
#Logstash实例从Elasticsearch轮询管道更改的频率。默认值为5s。
xpack.management.logstash.poll_interval
#指定一个以逗号分隔的管道ID列表，以注册集中式管道管理。更改此设置后，需要重新启动Logstash以获取更改。管道ID支持*作为匹配多个ID的通配符。
xpack.management.pipeline.id
#将存储Logstash管道配置和元数据的Elasticsearch实例。这可能是Logstash配置中输出部分指定的相同Elasticsearch实例，也可能是不同的实例。
xpack.management.elasticsearch.hosts
#访问es的账号
xpack.management.elasticsearch.username 
#访问es的密码
xpack.management.elasticsearch.password
#可选设置，允许您在Logstash需要使用代理来访问Elasticsearch集群时指定代理URL。
xpack.management.elasticsearch.proxy
#可选设置，允许您为Elasticsearch实例指定证书颁发机构的十六进制编码SHA-256指纹。
xpack.management.elasticsearch.ssl.ca_trusted_fingerprint
#可选设置，允许您为Elasticsearch实例的证书颁发机构指定.pem文件的路径。
xpack.management.elasticsearch.ssl.certificate_authority
#可选设置，提供Java密钥库（JKS）的路径以验证服务器的证书。
xpack.management.elasticsearch.ssl.truststore.path
#为信任库提供密码的可选设置。
xpack.management.elasticsearch.ssl.truststore.password
#可选设置，提供Java密钥库（JKS）的路径以验证客户端的证书。
xpack.management.elasticsearch.ssl.keystore.path
#为密钥库提供密码的可选设置。
xpack.management.elasticsearch.ssl.keystore.password
#如果您在Elastic Cloud中使用Elasticsearch，则应在此处指定标识符。此设置是xpack.management.elasticsearch.hosts的替代设置。如果配置了cloud_id，请使用xpack.management.elasticsearch。不应使用主机。此Elasticsearch实例将存储Logstash管道配置和元数据。
xpack.management.elasticsearch.cloud_id
#如果您在Elastic Cloud中使用Elasticsearch，可以在此处设置身份验证凭据。此设置是xpack.management.elasticsearch的替代选项。用户名和xpack.management.elasticsearch.password。如果配置了cloud_auth，则不应使用这些设置。您在这里指定的凭据应该是针对具有logstash_admin角色的用户的，该角色提供对系统索引的访问，以管理配置。
xpack.management.elasticsearch.cloud_auth
#使用Elasticsearch API密钥进行身份验证。请注意，此选项还需要使用SSL。API密钥格式为id:API_key，其中id和API_key由Elasticsearch创建API密钥API返回。
xpack.management.elasticsearch.api_key

6.监听Logstash配置

与所有Logstash管道一样，专用监视管道的目的是将事件发送到输出。在监控Logstash的情况下，输出始终是elasticsearch输出。但是，与普通的Logstash管道不同，输出通过xpack.monitoring.relasticsearch.*设置在logstash.yml设置文件中配置。

#是否开启监控，默认为false
xpack.monitoring.enabled
#配置ES地址
xpack.monitoring.elasticsearch.hosts
#连接ES的账号
xpack.monitoring.elasticsearch.username
#连接ES的密码
xpack.monitoring.elasticsearch.password

##如果在生产Elasticsearch集群上启用了SSL/TLS，请指定将用于验证集群中节点身份的受信任CA证书。
#要将CA证书添加到Logstash节点的受信任证书，可以使用certificate_authority设置指定PEM编码证书的位置
xpack.monitoring.elasticsearch.ssl.certificate_authority
#要添加CA而不将其加载到磁盘上，可以使用CA_trusted_fingerprint设置指定DER格式CA的十六进制编码SHA 256指纹
xpack.monitoring.elasticsearch.ssl.ca_trusted_fingerprint

##或者，您可以使用信任库（包含证书的Java密钥库文件）配置受信任的证书
#证书路径
xpack.monitoring.elasticsearch.ssl.truststore.path
#证书密码
xpack.monitoring.elasticsearch.ssl.truststore.password

##此外，还可以选择使用密钥库（包含证书的Java密钥库文件）设置客户端证书
#证书路径
xpack.monitoring.elasticsearch.ssl.keystore.path
#证书密码
xpack.monitoring.elasticsearch.ssl.keystore.password

#将sniffing设置为true，以启用对Elasticsearch集群的其他节点的发现。默认为false
xpack.monitoring.elasticsearch.sniffing