Logstash【从无到有从有到无】【L4】设置和运行Logstash

类型	描述	默认位置	设置
home	Logstash安装的主目录。	`{extract.path}- Directory created by unpacking the archive`
bin	二进制脚本，包括`logstash`启动Logstash和`logstash-plugin`安装插件	`{extract.path}/bin`
settings	配置文件，包括`logstash.yml`和`jvm.options`	`{extract.path}/config`	`path.settings`
logs	日志文件	`{extract.path}/logs`	`path.logs`
plugins	本地非Ruby-Gem插件文件。每个插件都包含在一个子目录中。建议仅用于开发。	`{extract.path}/plugins`	`path.plugins`
data	logstash及其插件用于任何持久性需求的数据文件。	`{extract.path}/data`	`path.data`

1.1.2.目录布局.zip和.tar.gz档案

Debian软件包和RPM软件包都将配置文件，日志和设置文件放在系统的适当位置：

类型	描述	默认位置	设置
home	Logstash安装的主目录	`/usr/share/logstash`
bin	二进制脚本包括`logstash`启动Logstash和`logstash-plugin`安装插件	`/usr/share/logstash/bin`
settings	配置文件，包括`logstash.yml`，`jvm.options`，和`startup.options`	`/etc/logstash`	`path.settings`
conf	Logstash管道配置文件	`/etc/logstash/conf.d/*.conf`	`See/etc/logstash/pipelines.yml`
logs	日志文件	`/var/log/logstash`	`path.logs`
plugins	本地非Ruby-Gem插件文件。每个插件都包含在一个子目录中。建议仅用于开发。	`/usr/share/logstash/plugins`	`path.plugins`
data	logstash及其插件用于任何持久性需求的数据文件。	`/var/lib/logstash`

1.1.3.Docker图像的目录布局

类型	描述	默认位置	设置
home	Logstash安装的主目录。	`/usr/share/logstash`
bin	二进制脚本，包括`logstash`启动Logstash和`logstash-plugin`安装插件	`/usr/share/logstash/bin`
settings	配置文件，包括`logstash.yml`和`jvm.options`	`/usr/share/logstash/config`	`path.settings`
conf	Logstash管道配置文件	`/usr/share/logstash/pipeline`	`path.config`
plugins	本地非Ruby-Gem插件文件。每个插件都包含在一个子目录中。建议仅用于开发。	`/usr/share/logstash/plugins`	`path.plugins`
data	logstash及其插件用于任何持久性需求的数据文件。	`/usr/share/logstash/data`	`path.data`

默认情况下，Logstash Docker容器不会创建日志文件。他们登录到标准输出。

1.2.Logstash配置文件

Logstash有两种类型的配置文件：管道配置文件，用于定义Logstash处理管道;以及设置文件，用于指定控制Logstash启动和执行的选项。

1.2.1.管道配置文件

在定义Logstash处理管道的各个阶段时，可以创建管道配置文件。在deb和rpm上，将管道配置文件放在/etc/logstash/conf.d目录中。Logstash尝试仅加载具有.conf扩展名的文件，/etc/logstash/conf.d directory并忽略所有其他文件。

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

1.2.2.设置文件

设置文件已在Logstash安装中定义。Logstash包括以下设置文件：

logstash.yml 包含Logstash配置标志。您可以在此文件中设置标志，而不是在命令行传递标志。您在命令行中设置的任何标志都会覆盖logstash.yml文件中的相应设置。有关详细信息，请参阅logstash.yml。
pipelines.yml 包含在单个Logstash实例中运行多个管道的框架和说明。有关详细信息，请参阅多个管道。
jvm.options 包含JVM配置标志。使用此文件设置总堆空间的初始值和最大值。您还可以使用此文件为Logstash设置区域设置。在单独的行上指定每个标志。此文件中的所有其他设置均被视为专家设置。
log4j2.properties 包含log4j 2库的默认设置。有关详细信息，请参阅Log4j2配置。
startup.options (Linux) 包含使用的选项system-install在脚本中/usr/share/logstash/bin建立相应的启动脚本为您的系统。安装Logstash软件包时，system-install脚本将在安装过程结束时执行，并使用指定的设置startup.options来设置用户，组，服务名称和服务描述等选项。默认情况下，Logstash服务安装在用户下logstash。该startup.options文件使您可以更轻松地安装Logstash服务的多个实例。您可以复制文件并更改特定设置的值。请注意，startup.options启动时不会读取该文件。如果要更改Logstash启动脚本（例如，更改Logstash用户或从其他配置路径读取），则必须重新运行system-install 脚本（以root身份）传递新设置。

1.3.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}支持表示法，在上面的示例中path.queue设置默认批处理延迟50和默认值/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文件包括以下设置。如果您使用的是X-Pack，请参阅Logstash中的X-Pack设置。

设置	描述	默认值
`node.name`	节点的描述性名称。	机器的主机名
`path.data`	Logstash及其插件用于满足任何持久需求的目录。	`LOGSTASH_HOME/data`
`pipeline.id`	管道的ID。	`main`
`pipeline.java_execution`	使用Java执行引擎。	真正
`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`
`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会检查配置文件中的更改。	`3s`
`config.debug`	设置为时`true`，将完全编译的配置显示为调试日志消息。你还必须设置`log.level: debug`。警告：日志消息将包含作为纯文本传递给插件配置的任何密码选项，并可能导致明文密码出现在您的日志中！	`false`
`config.support_escapes`	设置`true`为时，带引号的字符串将处理以下转义序列：`\n`成为文字换行符（ASCII 10）。`\r`成为文字回车（ASCII 13）。`\t`成为文字标签（ASCII 9）。`\\`成为一个字面反斜杠`\`。`\"`成为字面双引号。`\'`成为字面引号。	`false`
`modules`	配置时，`modules`必须在此表中描述的嵌套YAML结构中。	没有
`queue.type`	用于事件缓冲的内部排队模型。指定`memory`基于内存的传统队列，或`persisted`基于磁盘的ACKed队列（持久队列）。	`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.max_events`，`queue.max_bytes`则Logstash将使用先达到的标准。	1024mb（1g）
`queue.checkpoint.acks`	启用持久队列时强制检查点之前的最大ACK事件数（`queue.type: persisted`）。指定`queue.checkpoint.acks: 0`将此值设置为无限制。	1024
`queue.checkpoint.writes`	启用持久队列时强制检查点之前写入事件的最大数量（`queue.type: persisted`）。指定`queue.checkpoint.writes: 0`将此值设置为无限制。	1024
`queue.checkpoint.retry`	启用后，对于任何失败的检查点写入，Logstash将针对每次尝试检查点写入重试一次。不会重试任何后续错误。这是仅在具有非标准行为（如SAN）的文件系统上看到的失败检查点写入的解决方法，除特殊情况外，不建议这样做。	`false`
`queue.drain`	启用后，Logstash将等待直到持久队列耗尽，然后才能关闭。	`false`
`dead_letter_queue.enable`	用于指示Logstash启用插件支持的DLQ功能的标志。	`false`
`dead_letter_queue.max_bytes`	每个死信队列的最大大小。如果条目超过此设置会增加死信队列的大小，则会删除条目。	`1024mb`
`path.dead_letter_queue`	将为死信队列存储数据文件的目录路径。	`path.data/dead_letter_queue`
`http.host`	度量标准REST端点的绑定地址。	`"127.0.0.1"`
`http.port`	度量标准REST端点的绑定端口。	`9600`
`log.level`	日志级别。有效选项包括： `fatal` `error` `warn` `info` `debug` `trace`	`info`
`log.format`	日志格式。设置为`json`登录JSON格式，或`plain`使用`Object#.inspect`。	`plain`
`path.logs`	Logstash将其日志写入的目录。	`LOGSTASH_HOME/logs`
`path.plugins`	哪里可以找到自定义插件。您可以多次指定此设置以包含多个路径。插件预计将在一个特定的目录层次结构： `PATH/logstash/TYPE/NAME.rb`其中`TYPE`是`inputs`，`filters`，`outputs`，或`codecs`，并且`NAME`是插件的名称。	特定于平台的。请参阅Logstash目录布局。

1.4.Secrets密钥库用于安全设置

配置Logstash时，可能需要指定敏感设置或配置，例如密码。您可以使用Logstash密钥库来安全地存储秘密值，以便在配置设置中使用，而不是依赖文件系统权限来保护这些值。

将密钥及其密钥值添加到密钥库后，可以在配置敏感设置时使用密钥代替密钥值。

引用键的语法与环境变量的语法相同：

${KEY}

其中KEY是密钥的名称。

例如，假设密钥库包含一个ES_PWD使用值调用的密钥yourelasticsearchpassword：

在配置文件中，使用： output { elasticsearch {...password => "${ES_PWD}" } } }
在logstash.yml，使用：xpack.management.elasticsearch.password: ${ES_PWD}

请注意，Logstash密钥库与Elasticsearch密钥库不同。虽然Elasticsearch密钥库允许您elasticsearch.yml按名称存储值，但Logstash密钥库允许您指定可在Logstash配置中引用的任意名称。

目前不支持pipelines.yml从命令行（-e）引用密钥库数据。

从集中管道管理引用密钥库数据要求每个Logstash部署都具有密钥库的本地副本。

当Logstash解析settings（logstash.yml）或configuration（/etc/logstash/conf.d/*.conf）时，它会在解析环境变量之前解析密钥库中的密钥。

1.4.1.密钥库密码

您可以通过在名为的环境变量中存储密码来保护对Logstash密钥库的访问LOGSTASH_KEYSTORE_PASS。如果在设置此变量后创建Logstash密钥库，则密钥库将受密码保护。这意味着运行的Logstash实例需要可以访问环境变量。还必须为需要发出密钥库命令（添加，列出，删除等）的任何用户正确设置此环境变量。

建议使用密钥库密码，但可选。即使您没有设置密码，数据也会被加密。但是，强烈建议配置密钥库密码并向可能包含环境变量值的任何文件授予限制权限。如果您选择不设置密码，则可以跳过本节的其余部分。

例如：

set +o history
export LOGSTASH_KEYSTORE_PASS=mypassword
set -o history
bin/logstash-keystore create

此设置要求运行Logstash的用户LOGSTASH_KEYSTORE_PASS=mypassword定义环境变量。如果未定义环境变量，则Logstash无法访问密钥库。

从RPM或DEB程序包安装运行Logstash时，环境变量来自/etc/sysconfig/logstash。

您可能需要创建/etc/sysconfig/logstash。这个文件应该为所拥有的root与600权限。预期的格式 /etc/sysconfig/logstash是ENVIRONMENT_VARIABLE=VALUE，每行一个条目。
对于其他发行版，例如Docker或ZIP，请参阅运行时环境的文档（Windows，Docker等），以了解如何为运行Logstash的用户设置环境变量。确保只有该用户可以访问环境变量（以及密码）。

1.4.2.密钥库位置

密钥库必须位于Logstash的path.settings目录中。这是包含该logstash.yml文件的目录。对密钥库执行任何操作时，建议path.settings为keystore命令设置。例如，要在RPM / DEB安装上创建密钥库：

set +o history
export LOGSTASH_KEYSTORE_PASS=mypassword
set -o history
sudo -E /usr/share/logstash/bin/logstash-keystore --path.settings /etc/logstash create

有关默认目录位置的详细信息，请参阅Logstash目录布局。

如果path.settings未指向与该目录相同的目录，您将看到警告logstash.yml。

1.4.3.创建密钥库

要创建机密密钥库，请使用create：

bin/logstash-keystore create

在path.settings 配置设置定义的目录中创建密钥库。

建议您在创建密钥库时设置密钥库密码。

1.4.4.添加键

要存储敏感值，例如Elasticsearch的身份验证凭据，请使用以下add命令：

bin / logstash - keystore add ES_PWD

出现提示时，输入密钥的值。

1.4.5.列表键

要列出密钥库中定义的密钥，请使用：

bin/logstash-keystore list

1.4.6.删除键

要从密钥库中删除密钥，请使用：

bin/logstash-keystore remove ES_PWD

1.5.以命令行的方式运行Logstash

要从命令行运行Logstash，请使用以下命令

bin/logstash [options]

要从Windows命令行运行Logstash，请使用以下命令：

bin/logstash.bat [options]

在命令行（command-line）中，参数options是可以指定控制Logstash执行的标志。bin目录的位置因平台而异。请参阅Logstash目录布局以查找bin\logstash系统上的位置。

下示例运行Logstash并加载mypipeline.conf文件中定义的Logstash配置：

bin/logstash -f mypipeline.conf

您在命令行中设置的任何标志都会覆盖logstash.yml 中的相应设置，但文件本身不会更改。它仍然是后续Logstash运行的原样。

在测试Logstash时，指定命令行选项很有用。但是，在生产环境中，我们建议您使用 logstash.yml来控制Logstash执行。使用设置文件可以更轻松地指定多个选项，它为您提供了一个可版本化的文件，您可以使用该文件为每次运行一致地启动Logstash。

1.5.1.命令行标志（ommand-Line Flags） $1{\color{Cyan} }$

logstash有以下标志。您可以使用--help标志来显示此信息。

--node.name NAME

指定此Logstash实例的名称。如果没有给出值，则默认为当前主机名。

-f, --path.config CONFIG_PATH

从特定文件或目录加载Logstash配置。如果给出了目录，则该目录中的所有文件将按字典顺序连接，然后解析为单个配置文件。不支持多次指定此标志。如果多次指定此标志，则Logstash将使用最后一次出现（例如，与之-f foo -f bar 相同-f bar）。

您可以指定通配符（globs），任何匹配的文件将按上述顺序加载。例如，您可以使用通配符功能按名称加载特定文件：

bin/logstash --debug -f '/tmp/{one,two,three}'

使用此命令，Logstash串接三个配置文件/tmp/one，/tmp/two以及 /tmp/three和他们解析到一个单一的配置。

-e, --config.string CONFIG_STRING

使用给定的字符串作为配置数据。语法与配置文件相同。如果未指定输入，则以下内容用作默认输入：input { stdin { type => stdin } }如果未指定输出，则以下内容用作默认输出：output { stdout { codec => rubydebug } }。如果您希望同时使用这两个默认值，请使用空字符串作为-e标志。默认值为nil。

--java-execution

指定false此选项以还原为旧的Ruby执行引擎，而不是默认的Java执行引擎。

--plugin-classloaders

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

--modules

启动命名模块。与-M为指定模块的默认变量赋值的选项一起使用。如果--modules在命令行中使用，logstash.yml则将忽略任何模块，其中的任何设置都将被忽略。该标志与-f和-e标志互斥。只有一个-f，-e或者--modules可以指定。可以通过用逗号分隔多个模块，或者--modules多次调用标志来指定多个模块。

-M, --modules.variable

为模块的可配置选项指定值。分配变量的格式适用 -M "MODULE_NAME.var.PLUGIN_TYPE.PLUGIN_NAME.KEY_NAME=value"于Logstash变量。对于其他设置，它将是-M "MODULE_NAME.KEY_NAME.SUB_KEYNAME=value"。-M可以根据需要多次使用该标志。如果未-M指定任何选项，则将使用该设置的默认值。该-M标志仅与--modules 标志一起使用。如果没有--modules标志，它将被忽略。

--pipeline.id ID

设置管道的ID。默认是main。

-w, --pipeline.workers COUNT

设置要运行的管道工作数量。此选项设置将并行执行管道的过滤器和输出阶段的工作器数。如果发现事件正在备份，或者CPU未饱和，请考虑增加此数量以更好地利用机器处理能力。默认值是主机CPU核心的数量。

-b, --pipeline.batch.size SIZE

管道要使用的批处理大小。此选项定义在尝试执行其过滤器和输出之前，单个工作线程将从输入收集的最大事件数。默认值为125个事件。较大的批量通常更有效，但代价是增加了内存开销。您可能需要在jvm.options配置文件中增加JVM堆空间。有关详细信息，请参阅Logstash配置文件。

-u, --pipeline.batch.delay DELAY_IN_MS

创建管道批次时，轮询下一个事件需要等待多长时间。此选项定义在将较小的批处理调度到筛选器和输出之前轮询下一个事件时等待的时间长度（以毫秒为单位）。默认值为50毫秒。

--pipeline.unsafe_shutdown

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

--path.data PATH

这应该指向一个可写目录。Logstash将在需要存储数据时使用此目录。插件也可以访问此路径。默认值是在Logstash主目录下的data目录。

-p, --path.plugins PATH

自定义插件的路径。可以多次给出该标志以包括多个路径。插件预计将在一个特定的目录层次结构：PATH/logstash/TYPE/NAME.rb，其中TYPE是inputs，filters，outputs，或codecs，并且NAME是插件的名称。

-l, --path.logs PATH

将Logstash内部日志写入的目录。

--log.level LEVEL

设置Logstash的日志级别。可能的值是：

fatal：记录应用程序中止后通常会出现的非常严重的错误消息
error：记录错误
warn：日志警告
info：log verbose info（这是默认值）
debug：日志调试信息（面向开发人员）
trace：记录超出调试信息的更细粒度的消息

--config.debug

将完全编译的配置显示为调试日志消息（您还必须已--log.level=debug启用）。警告：日志消息将包含作为纯文本传递给插件配置的任何密码选项，并可能导致明文密码出现在您的日志中！

-i, --interactive SHELL

Drop to shell instead of running as normal. Valid shells are "irb" and "pry".

使用shell脚本运行来代替正常的运行方式。有效的shells是irb或pry。

-V, --version

发出Logstash及其好友的版本，然后退出。

-t, --config.test_and_exit

检查配置是否有效语法，然后退出。请注意，使用此标志不会检查grok模式的正确性。Logstash可以从目录中读取多个配置文件。如果将此标志组合在一起--log.level=debug，Logstash将记录组合的配置文件，使用它来自的源文件注释每个配置块。

-r, --config.reload.automatic

轮询配置位置以进行更改的频率。默认值为“3s”。

--http.host HTTP_HOS

Web API绑定主机。此选项指定度量标准REST端点的绑定地址。默认值为“127.0.0.1”。

--http.port HTTP_PORT

Web API http端口。此选项指定度量标准REST端点的绑定端口。默认值为9600-9700。此设置接受格式9600-9700的范围。Logstash将获取第一个可用端口。

--log.format FORMAT

指定Logstash是否应该以JSON格式（每行一个事件）或纯文本（使用Ruby的Object＃inspect）编写自己的日志。默认为“plain”。

--path.settings SETTINGS_DIR

设置包含logstash.yml 设置文件的目录以及log4j日志记录配置。这也可以通过LS_SETTINGS_DIR环境变量设置。默认值是在Logstash主目录下config的目录。

-h, --help

打印帮助

1.6.在Debian或RPM上运行Logstash服务

安装后不会自动启动Logstash。如何启动和停止Logstash取决于您的系统是使用systemd，upstart还是SysV。

以下是一些常见的操作系统和版本，以及它们使用的相应启动样式。此列表旨在提供信息，而非详尽无遗。

分配	服务体系
Ubuntu 16.04 and newer	systemd
Ubuntu 12.04 through 15.10	upstart
Debian 8 "jessie" and newer	systemd
Debian 7 "wheezy" and older	sysv
CentOS (and RHEL) 7 and newer	systemd
CentOS (and RHEL) 6	upstart

1.6.1.使用Systemd运行Logstash

像Debian Jessie、Ubuntu 15.10+和许多SUSE衍生物这样的发行版都使用systemd和systemctl命令来启动和停止服务。Logstash将systemd单元文件放在/etc/systemd/system中，用于deb和rpm。安装软件包后，您可以启动Logstash与:

sudo systemctl start logstash.service

1.6.2.使用Upstart运行Logstash

对于使用upstart的系统，您可以使用以下命令启动Logstash：

sudo initctl start logstash

新手系统的自动生成配置文件是/etc/init/logstash.conf。

1.6.3.使用SysV运行Logstash

对于使用SysV的系统，您可以使用以下命令启动Logstash：

sudo /etc/init.d/logstash start

SysV系统的自动生成配置文件是/etc/init.d/logstash。

1.7.在Docker上运行Logstash

Logstash的Docker镜像可从Elastic Docker注册表获得。基本镜像是centos：7。

有关所有已发布的Docker镜像和标记的列表，请访问 www.docker.elastic.co。源代码在 GitHub中。

这些r镜像可以在Elastic许可下免费使用。它们包含开源和免费商业功能以及付费商业功能。开始为期30天的试用，试用所有付费商业功能。有关弹性许可级别的信息，请参阅“ 订阅”页面。

参考：Docker与VM虚拟机的区别以及Docker的特点

Docker最全教程菜鸟教程

1.7.1.镜像获取

获取Docker的Logstash就像docker pull对Elastic Docker注册表发出命令一样简单。

docker pull docker.elastic.co/logstash/logstash:7.3.1

或者，您可以下载仅包含Apache 2.0许可下可用功能的其他Docker映像。要下载图像，请访问www.docker.elastic.co。

1.8.为Docker配置Logstash

Logstash区分两种类型的配置：设置和管道配置。

1.8.1.管道配置

必须将管道配置放在Logstash可以找到的位置。默认情况下，容器将查找/usr/share/logstash/pipeline/管道配置文件。

在此示例中，我们使用绑定装入的卷通过以下docker run命令提供配置：

docker run --rm -it -v ~/pipeline/:/usr/share/logstash/pipeline/ docker.elastic.co/logstash/logstash:7.3.1

然后，logstash将主机目录~/pipeline/中的每个文件作为管道配置进行分析。

如果您不向Logstash提供配置，它将使用最小配置运行，该配置侦听来自Beats输入插件的消息并回显任何接收到的消息stdout。在这种情况下，启动日志将类似于以下内容：

Sending Logstash logs to /usr/share/logstash/logs which is now configured via log4j2.properties.
[2016-10-26T05:11:34,992][INFO ][logstash.inputs.beats    ] Beats inputs: Starting input listener {:address=>"0.0.0.0:5044"}
[2016-10-26T05:11:35,068][INFO ][logstash.pipeline        ] Starting pipeline {"id"=>"main", "pipeline.workers"=>4, "pipeline.batch.size"=>125, "pipeline.batch.delay"=>5, "pipeline.max_inflight"=>500}
[2016-10-26T05:11:35,078][INFO ][org.logstash.beats.Server] Starting server on port: 5044
[2016-10-26T05:11:35,078][INFO ][logstash.pipeline        ] Pipeline main started
[2016-10-26T05:11:35,105][INFO ][logstash.agent           ] Successfully started Logstash API endpoint {:port=>9600}

这是镜像的默认配置，在中定义 /usr/share/logstash/pipeline/logstash.conf。如果这是您正在观察的行为，请确保正确选取管道配置，并确保要替换其中一个logstash.conf或整个pipeline目录。

1.8.2.设置

该图像提供了几种配置设置的方法。传统方法是提供自定义logstash.yml文件，但也可以使用环境变量来定义设置。

1.8.2.1.绑定的设置文件

设置文件也可以通过bind-mounts提供。Logstash希望找到它们/usr/share/logstash/config/。

可以提供包含所有所需文件的整个目录：

docker run --rm -it -v ~/settings/:/usr/share/logstash/config/ docker.elastic.co/logstash/logstash:7.3.1

或者，可以安装单个文件：

docker run --rm -it -v ~/settings/logstash.yml:/usr/share/logstash/config/logstash.yml docker.elastic.co/logstash/logstash:7.3.1

绑定的配置文件将在它们在主机系统上的容器中保留相同的权限和所有权。确保设置权限，使文件可读，并且理想情况下，容器的logstash用户（UID 1000）不可写

1.8.2.2.自定义图像

当然，绑定配置不是唯一的选择。如果您更喜欢不可变基础结构方法，则可以使用以下方法准备包含配置的自定义映像Dockerfile ：

FROM docker.elastic.co/logstash/logstash:7.3.1
RUN rm -f /usr/share/logstash/pipeline/logstash.conf
ADD pipeline/ /usr/share/logstash/pipeline/
ADD config/ /usr/share/logstash/config/

请务必logstash.conf在自定义图像中替换或删除，以便不保留基本图像中的示例配置。

1.8.2.3.环境变量配置

在Docker下，可以通过环境变量配置Logstash设置。容器启动时，辅助进程会检查环境中是否有可映射到Logstash设置的变量。在容器启动时，将环境中的设置合并到logstash.yml。

为了与容器编排系统兼容，这些环境变量以全部大写写入，下划线为单词分隔符

这里显示了一些示例翻译：

表1. Docker环境变量示例

环境变量	Logstash设置
`PIPELINE_WORKERS`	`pipeline.workers`
`LOG_LEVEL`	`log.level`
`XPACK_MONITORING_ENABLED`	`xpack.monitoring.enabled`

通常，可以使用此技术配置设置文档中列出的任何设置

使用环境变量定义设置会导致logstash.yml进行适当的修改。如果logstash.yml从主机系统进行绑定挂载，则此行为可能不合需要。因此，不建议将绑定装载技术与环境变量技术结合使用。最好选择一种方法来定义Logstash设置。

1.8.3.Docker默认

使用Docker镜像时，以下设置具有不同的默认值：

`http.host`	`0.0.0.0`
`xpack.monitoring.elasticsearch.hosts`	`http://elasticsearch:9200`

图像中xpack.monitoring.elasticsearch.hosts未定义该设置-oss。

这些设置在默认值中定义logstash.yml。可以使用自定义logstash.yml或通过环境变量覆盖它们。

如果要替换logstash.yml为自定义版本，请确保将上述默认值复制到自定义文件中（如果要保留它们）。如果没有，它们将被新文件“屏蔽”。

1.8.4.记录配置

在Docker下，Logstash日志默认转到标准输出。

要更改此行为，请使用上述任何技术替换该文件/usr/share/logstash/config/log4j2.properties。

1.9.在Windows上运行Logstash

在阅读本节之前，请参阅安装Logstash以开始使用。您还需要熟悉从命令行运行Logstash，因为命令行选项用于测试在Windows上运行的Logstash。

在测试Logstash时，指定命令行选项很有用。但是，在生产环境中，我们建议您使用logstash.yml来控制Logstash执行。使用设置文件可以更轻松地指定多个选项，它为您提供了一个可版本化的文件，您可以使用该文件为每次运行一致地启动Logstash。

安装后不会自动启动Logstash。如何在Windows上启动和停止Logstash取决于您是要将其作为服务（使用NSSM）手动运行，还是将其作为计划任务运行。本指南提供了Logstash在Windows上运行的一些方法的示例。

建议在将Logstash作为服务或计划任务运行之前，通过手动运行Logstash来验证配置是否正常工作。

1.9.1.在Windows上验证JVM先决条件

安装支持的JVM后，打开PowerShell会话并运行以下命令以验证是否JAVA_HOME已设置以及Java版本：

Write-Host $env:JAVA_HOME

输出应指向JVM软件所在的位置，例如：

PS C:\> Write-Host $env:JAVA_HOME
C:\Program Files\Java\jdk-11.0.3

如果JAVA_HOME未设置，请执行以下操作之一：

使用GUI设置：

导航到Windows 环境变量窗口
在Environmental Variables窗口中，编辑JAVA_HOME以指向JDK软件所在的位置，例如： C:\Program Files\Java\jdk-11.0.3

使用PowerShell设置：

1.在管理PowerShell会话中，执行以下SETX命令：

PS C:\Windows\system32> SETX /m JAVA_HOME "C:\Program Files\Java\jdk-11.0.3"
PS C:\Windows\system32> SETX /m PATH "$env:PATH;C:\Program Files\Java\jdk-11.0.3\bin;"

2.退出PowerShell，然后打开一个新的PowerShell会话并运行Write-Host $env:JAVA_HOME以进行验证

Java -version

此命令生成类似于以下内容的输出：

PS C:\> Java -version
java version "11.0.3" 2019-04-16 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.3+12-LTS)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.3+12-LTS, mixed mode)

截至本文档发布时，请在继续之前查看影响Java 11的已知问题。

一旦设置并运行Logstash并验证了JVM先决条件，就可以继续。

对于下面列出的示例，我们运行Windows Server 2016，Java 11.0.3，已将Logstash ZIP包解压缩到C:\logstash-7.3.1\，并使用下面显示的示例 syslog.conf文件（存储在其中 C:\logstash-7.3.1\config\）。

1.9.2.运行Logstash手动

可以使用PowerShell手动运行Logstash 。打开管理PowerShell会话，然后运行以下命令：

PS C:\Windows\system32> cd C:\logstash-7.3.1\
PS C:\logstash-7.3.1> .\bin\logstash.bat -f .\config\syslog.conf

在生产环境中，我们建议您使用logstash.yml来控制Logstash执行。

等待出现以下消息，以确认Logstash已成功启动：

[logstash.runner          ] Starting Logstash {"logstash.version"=>"7.3.1"}
[logstash.inputs.udp      ] Starting UDP listener {:address=>"0.0.0.0:514"}
[logstash.agent           ] Successfully started Logstash API endpoint {:port=>9600}

1.9.3.使用NSSM Logstash作为服务运行

建议您在继续之前通过手动运行Logstash来验证配置是否正常工作。

下载NSSM，然后从 nssm-<version.number>\win64\nssm.exe到C:\logstash-7.3.1\bin\提取nssm.exe。然后打开管理 PowerShell会话，然后运行以下命令：

PS C:\Windows\system32> cd C:\logstash-7.3.1\
PS C:\logstash-7.3.1> .\bin\nssm.exe install logstash

一旦NSSM service installer出现窗口，请在下面的参数Application标签：

在Application标签中：
路径：路径logstash.bat：C:\logstash-7.3.1\bin\logstash.bat
启动目录：bin目录的路径：C:\logstash-7.3.1\bin
参数：对于此示例，启动Logstash： -f C:\logstash-7.3.1\config\syslog.conf

在生产环境中，我们建议您使用logstash.yml来控制Logstash执行。

在Details选项卡中查看并进行必要的更改：
确保Startup Type设置得当
将Display name和Description字段设置为相关的内容
查看任何其他所需设置（例如我们没有进行任何其他更改）
务必确定是否需要设置Log on用户
验证Service name是否正确设置
对于这个例子，我们将把我们设置为 logstash-syslog
点击 Install Service
出现窗口时单击“ 确定Service "logstash-syslog" installed successfully! ”

使用NSSM安装服务后，请按照PowerShell管理服务文档验证并启动该服务。

1.9.4.使用任务计划程序运行Logstash

建议您在继续之前通过手动运行Logstash来验证配置是否正常工作。

打开Windows 任务计划程序，然后单击Create Task“操作”窗口。在Actions选项卡中指定以下参数：

在Actions标签中：
- 单击New，然后指定以下内容：
- 行动： Start a program
- 程序/脚本： C:\logstash-7.3.1\bin\logstash.bat
- 添加参数： -f C:\logstash-7.3.1\config\syslog.conf
- 开始于： C:\logstash-7.3.1\bin\
  
  在生产环境中，我们建议您使用logstash.yml来控制Logstash执行。
检查，并在必要的任何变化General，Triggers，Conditions，和Settings标签。
单击OK以完成创建计划任务。
创建新任务后，要么等待它按计划运行，要么选择服务，然后单击Run以启动任务。

可以通过选择服务，然后单击End“任务计划程序”窗口来停止Logstash 。

1.9.5.示例Logstash配置

我们将配置Logstash以使用此配置通过端口514侦听syslog消息（文件名为syslog.conf）：

# Sample Logstash configuration for receiving
# UDP syslog messages over port 514

input {
  udp {
    port => 514
    type => "syslog"
  }
}

output {
  elasticsearch { hosts => ["localhost:9200"] }
  stdout { codec => rubydebug }
}

1.10.日志

Logstash在其操作期间发出内部日志，这些日志位于LS_HOME/logs（或/var/log/logstash用于DEB / RPM）。默认日志记录级别为INFO。Logstash的日志框架基于 Log4j 2框架，其大部分功能直接暴露给用户。

您可以配置特定子系统，模块或插件的日志记录。

当您需要调试问题，特别是插件问题时，请考虑增加日志记录级别DEBUG以获取更详细的消息。例如，如果您正在调试Elasticsearch Output的问题，则可以仅为该组件增加日志级别。这种方法可以减少过度记录的噪音，并帮助您专注于问题区域。

您可以使用该log4j2.properties文件或Logstash API 配置日志记录

log4j2.properties file。通过该log4j2.properties 文件所做的更改要求您重新启动Logstash以使更改生效。更改将在后续重新启动时保留。
Logging API。通过Logging API进行的更改立即生效，无需重新启动。重新启动Logstash后，更改不会保留。

1.10.1.Log4j2配置

Logstash附带一个log4j2.properties带有开箱即用设置的文件。您可以修改此文件以更改轮换策略，类型和其他 log4j2配置。

您必须重新启动Logstash才能应用对此文件所做的任何更改。log4j2.properties重新启动Logstash后更改将保持不变。

这是一个使用示例outputs.elasticsearch：

logger.elasticsearchoutput.name = logstash.outputs.elasticsearch
logger.elasticsearchoutput.level = debug

1.10.2.记录API

对于临时日志记录更改，修改log4j2.properties文件并重新启动Logstash会导致不必要的停机时间。相反，您可以通过日志记录API动态更新日志记录级别。这些设置立即生效，无需重启。

默认情况下，日志记录API尝试绑定到tcp:9600。如果此端口已被另一个Logstash实例使用，则需要使用--http.port指定的标志启动Logstash 以绑定到其他端口。有关更多信息，请参阅命令行标志。

1.10.3.检索日志记录配置列表

要检索运行时可用的日志记录子系统列表，您可以执行GET请求_node/logging

curl -XGET 'localhost:9600/_node/logging?pretty'

响应示例：

{
...
  "loggers" : {
    "logstash.agent" : "INFO",
    "logstash.api.service" : "INFO",
    "logstash.basepipeline" : "INFO",
    "logstash.codecs.plain" : "INFO",
    "logstash.codecs.rubydebug" : "INFO",
    "logstash.filters.grok" : "INFO",
    "logstash.inputs.beats" : "INFO",
    "logstash.instrument.periodicpoller.jvm" : "INFO",
    "logstash.instrument.periodicpoller.os" : "INFO",
    "logstash.instrument.periodicpoller.persistentqueue" : "INFO",
    "logstash.outputs.stdout" : "INFO",
    "logstash.pipeline" : "INFO",
    "logstash.plugins.registry" : "INFO",
    "logstash.runner" : "INFO",
    "logstash.shutdownwatcher" : "INFO",
    "org.logstash.Event" : "INFO",
    "slowlog.logstash.codecs.plain" : "TRACE",
    "slowlog.logstash.codecs.rubydebug" : "TRACE",
    "slowlog.logstash.filters.grok" : "TRACE",
    "slowlog.logstash.inputs.beats" : "TRACE",
    "slowlog.logstash.outputs.stdout" : "TRACE"
  }
}

1.10.4.更新日志级别

预先添加子系统，模块或插件的名称logger.。

这是一个使用示例outputs.elasticsearch：

curl -XPUT 'localhost:9600/_node/logging?pretty' -H 'Content-Type: application/json' -d'
{
    "logger.logstash.outputs.elasticsearch" : "DEBUG"
}
'

当此设置生效时，Logstash会为配置中指定的所有 Elasticsearch输出发出DEBUG级别日志。请注意，此新设置是暂时的，无法在重新启动后继续运行。

如果要在重新启动后保留日志记录更改，请将其添加到其中log4j2.properties。

1.10.5.重置动态日志级别

要重置可能已通过日志记录API动态更改的任何日志记录级别，请发送PUT请求 _node/logging/reset。所有日志记录级别将恢复为log4j2.properties文件中指定的值。

curl -XPUT 'localhost:9600/_node/logging/reset?pretty'

1.10.6.日志文件位置

您可以使用--path.logs设置指定日志文件位置。

1.10.7.Slowlog

Logstash的Slowlog添加了在特定事件花费异常时间通过管道时记录的功能。就像普通的应用程序日志一样，您可以在--path.logs目录中找到slowlogs 。logstash.yml使用以下选项在设置文件中配置Slowlog ：

slowlog.threshold.warn (default: -1)
slowlog.threshold.info (default: -1)
slowlog.threshold.debug (default: -1)
slowlog.threshold.trace (default: -1)

默认情况下禁用Slowlog。默认阈值设置 -1nanos为表示无限阈值。不会调用Slowlog。

1.10.8.启用Slowlog

这些slowlog.threshold字段使用时间值格式，可以实现各种触发间隔。您可以使用以下时间单位指定范围：（nanos纳秒），micros（微秒），ms（毫秒），s （秒），m（分钟），h（小时），d（日）。

当您提高日志级别时，Slowlog会变得更加敏感并记录更多事件。

例：

slowlog.threshold.warn: 2s
slowlog.threshold.info: 1s
slowlog.threshold.debug: 500ms
slowlog.threshold.trace: 100ms

在这个例子中：

如果日志级别设置为warn，则日志显示处理时间超过2秒的事件。
如果日志级别设置为info，则日志显示要处理的时间超过1秒的事件。
如果日志级别设置为trace，则日志显示要处理的时间超过100毫秒的事件。
如果日志级别设置为debug，则日志显示处理时间超过500毫秒的事件。

日志包括导致速度缓慢的完整事件和过滤器配置。

1.11.关闭Logstash

如果您将Logstash作为服务运行，请使用以下命令之一来停止它

systemd systemctl stop
upstart logstash initctl stop logstash
sysv /etc/init.d/logstash stop

如果您直接在POSIX系统的控制台中运行Logstash，则可以通过将SIGTERM发送到Logstash进程来停止它。例如：

kill -TERM {logstash_pid}

或者，在控制台中输入Ctrl-C。

1.11.1.控制关机期间会发生什么？

当您尝试关闭正在运行的Logstash实例时，Logstash会在安全关闭之前执行几个步骤。它必须：

停止所有输入，过滤和输出插件
处理所有运行中的事件
终止Logstash进程

以下条件会影响关闭过程：

输入插件以慢速接收数据。
缓慢的过滤器，如执行Ruby过滤器sleep(10000)或执行非常繁重的查询的Elasticsearch过滤器。
一个断开连接的输出插件，等待重新连接以刷新正在进行的事件。

这些情况使关闭过程的持续时间和成功变得不可预测。

Logstash有一个停顿检测机制，可以在关机期间分析管道和插件的行为。此机制生成有关内部队列中的飞行事件计数和繁忙工作线程列表的定期信息。

要在停止关闭的情况下强制终止Logstash，请在--pipeline.unsafe_shutdown启动Logstash时使用该标志。

由于任何其他原因，不安全的关闭，Logstash进程的强制终止或Logstash进程的崩溃可能导致数据丢失（除非您已启用Logstash以使用持久队列）。尽可能安全地关闭Logstash。

1.11.2.失速(stall)检测示例

在此示例中，缓慢的过滤器执行会阻止管道执行干净关闭。由于Logstash以--pipeline.unsafe_shutdown标志启动，因此关闭会导致丢失20个事件。

bin/logstash -e 'input { generator { } } filter { ruby { code => "sleep 10000" } }
  output { stdout { codec => dots } }' -w 1 --pipeline.unsafe_shutdown
Pipeline main started
^CSIGINT received. Shutting down the agent. {:level=>:warn}
stopping pipeline {:id=>"main", :level=>:warn}
Received shutdown signal, but pipeline is still waiting for in-flight events
to be processed. Sending another ^C will force quit Logstash, but this may cause
data loss. {:level=>:warn}
{"inflight_count"=>125, "stalling_thread_info"=>{["LogStash::Filters::Ruby",
{"code"=>"sleep 10000"}]=>[{"thread_id"=>19, "name"=>"[main]>worker0",
"current_call"=>"(ruby filter code):1:in `sleep'"}]}} {:level=>:warn}
The shutdown process appears to be stalled due to busy or blocked plugins.
Check the logs for more information. {:level=>:error}
{"inflight_count"=>125, "stalling_thread_info"=>{["LogStash::Filters::Ruby",
{"code"=>"sleep 10000"}]=>[{"thread_id"=>19, "name"=>"[main]>worker0",
"current_call"=>"(ruby filter code):1:in `sleep'"}]}} {:level=>:warn}
{"inflight_count"=>125, "stalling_thread_info"=>{["LogStash::Filters::Ruby",
{"code"=>"sleep 10000"}]=>[{"thread_id"=>19, "name"=>"[main]>worker0",
"current_call"=>"(ruby filter code):1:in `sleep'"}]}} {:level=>:warn}
Forcefully quitting logstash.. {:level=>:fatal}

如果--pipeline.unsafe_shutdown未启用，Logstash将继续运行并定期生成这些报告。