Elasticsearch 输出插件

示例：基本默认配置

output {
    elasticsearch {
        hosts => "hostname"
        data_stream => "true"
    }
}

此示例显示了处理数据流的最小设置。具有data_stream.*`字段的事件将路由到相应的数据流。如果缺少这些字段，路由将默认为logs-generic-default。

示例：自定义数据流名称

output {
    elasticsearch {
        hosts => "hostname"
        data_stream => "true"
        data_stream_type => "metrics"
        data_stream_dataset => "foo"
        data_stream_namespace => "bar"
    }
}

要执行的 Elasticsearch 操作。有效的操作有：

有关操作的更多详细信息，请查看 Elasticsearch bulk API 文档。

使用 Elasticsearch API 密钥进行身份验证。请注意，此选项还需要 SSL/TLS，可以通过提供 cloud_id、HTTPS hosts 列表或设置 ssl_enabled => true 来启用。

格式为 id:api_key，其中 id 和 api_key 是 Elasticsearch 创建 API 密钥 API 返回的。

执行 _bulk 请求的 HTTP 路径。* 此默认批量路径是 path 参数的值与 /_bulk?filter_path=errors,items.*.error,items.*.status 的连接。* filter_path 查询参数附加到批量路径，以减少 logstash 和 elasticsearch 之间的负载。但是，如果自定义 filter_path 查询参数包含在 bulk_path 设置中，则将使用该值。

要信任的 SSL 证书颁发机构的 SHA-256 指纹，例如 Elasticsearch 集群的自动生成的自签名 CA。

云身份验证字符串（“<用户名>:<密码>”格式）是 user/password 对的替代方案。

有关更多详细信息，请查看 Logstash-to-Cloud 文档。

来自 Elastic Cloud Web 控制台的 Cloud ID。如果设置了，则不应使用 hosts。

有关更多详细信息，请查看 Logstash-to-Cloud 文档。

gzip 压缩级别。将此值设置为 0 将禁用压缩。压缩级别必须在 1（最佳速度）到 9（最佳压缩）的范围内。

增加压缩级别将减少网络使用量，但会增加 CPU 使用量。

定义是否将数据索引到 Elasticsearch 数据流中。只有启用此设置后，才会使用其他 data_stream_* 设置。

当提供的配置与数据流兼容且此值设置为 auto 时，Logstash 将输出作为数据流处理。请注意，要使数据流正常工作，必须启用ECS 兼容性（设置为 v1 或 v8）。

通过使用 %{[data_stream][type]}-%{[data_stream][dataset]}-%{[data_stream][namespace]} 格式，使用特定事件字段派生数据流名称，从而自动路由事件。

如果启用，data_stream.* 事件字段将优先于 data_stream_type、data_stream_dataset 和 data_stream_namespace 设置，但如果事件中缺少任何字段，则会回退到它们。

用于在索引时构造数据流的数据集。

用于在索引时构造数据流的命名空间。

如果事件中缺少 data_stream.* 事件字段，则自动添加并同步这些字段。这确保字段与接收事件的数据流名称匹配。

用于在索引时构造数据流的数据流类型。目前，仅支持 logs、metrics、synthetics 和 traces。

Elasticsearch Bulk API 中，被视为有效，可以将事件移动到死信队列的单操作错误代码列表。此列表是对为此功能考虑的普通错误代码 400 和 404 的补充。重新使用相同的预定义代码表示成功、DLQ 或冲突被认为是配置错误。该选项接受与 HTTP 错误代码对应的自然数列表。

如果启用，失败的索引名称插值事件将进入死信队列。

为更新模式启用 doc_as_upsert。如果 Elasticsearch 中不存在 document_id，则使用 source 创建新文档。

索引的文档 ID。用于覆盖 Elasticsearch 中具有相同 ID 的现有条目非常有用。

此选项设置用于写入事件的文档类型。通常，您应该尝试将相似的事件写入同一类型。此处可以使用字符串扩展 %{foo}。如果您没有为此选项设置值

控制此插件与Elastic Common Schema (ECS)的兼容性，包括安装 ECS 兼容的索引模板。此设置的值会影响 默认 值

传递一组键值对作为发送到 Elasticsearch 节点的每个请求的标头。标头将用于任何类型的请求（_bulk 请求、模板安装、健康检查和嗅探）。这些自定义标头将被诸如 compression_level 之类的设置覆盖。

当后端被标记为不可用时，会将 HEAD 请求发送到此 HTTP 路径，该请求在后台发送，以查看它是否再次可用，然后再有资格再次服务请求。如果您有自定义防火墙规则，则可能需要更改此项

设置远程实例的主机。如果给定一个数组，它将在 hosts 参数中指定的主机之间进行请求的负载均衡。请记住，http 协议使用 http 地址（例如，9200，而不是 9300）。

示例

`"127.0.0.1"`
`["127.0.0.1:9200","127.0.0.2:9200"]`
`["http://127.0.0.1"]`
`["https://127.0.0.1:9200"]`
`["https://127.0.0.1:9200/mypath"]` (If using a proxy on a subpath)

从 hosts 列表中排除专用的主节点，以防止 Logstash 将批量请求发送到主节点。此参数应仅引用 Elasticsearch 中的数据节点或客户端节点。

此处 URL 中存在的任何特殊字符都必须进行 URL 转义！这意味着例如 # 应输入为 %23。

将 true 设置为启用请求上的 gzip 压缩级别 1。

此设置允许您通过压缩每个批量 请求 到 Elasticsearch，来减少此插件的出站网络流量。

如果 Elasticsearch 集群运行的是 Elasticsearch 版本 7.0.0 或更高版本，并且启用了 ILM 功能，则 auto 的默认设置会自动启用索引生命周期管理，否则禁用它。

即使 Elasticsearch 集群支持 ILM，将此标志设置为 false 也将禁用索引生命周期管理功能。如果 Elasticsearch 集群支持索引生命周期管理功能，则将此标志设置为 true 将启用该功能。这是在早于 7.0.0 版本的 Elasticsearch 版本上启用索引生命周期管理所必需的。

用于生成由索引生命周期管理管理的索引的模式。模式中指定的值将被附加到写入别名，并在 ILM 创建新索引时自动递增。

指定 ilm 模式时可以使用日期数学，详情请参阅Rollover API 文档。

修改此设置以使用自定义索引生命周期管理策略，而不是默认策略。如果未设置此值，则默认策略将自动安装到 Elasticsearch 中。

翻转别名是使用索引生命周期管理管理的索引将写入的别名。

要将事件写入的索引目标。可以指向索引、别名或数据流。可以使用 %{foo} 语法进行动态设置。默认值将按天对索引进行分区，以便您可以更轻松地删除旧数据或仅搜索特定日期范围。索引不得包含大写字符。对于每周索引，建议使用 ISO 8601 格式，例如 logstash-%{+xxxx.ww}。Logstash 使用Joda 格式，并且每个事件的 @timestamp 字段用作日期的来源。

从 Logstash 1.3 开始，如果名为template_name的模板尚不存在，则在 Logstash 启动期间将模板应用于 Elasticsearch。默认情况下，此模板的内容是 logstash-%{+YYYY.MM.dd} 的默认模板，它始终匹配基于模式 logstash-* 的索引。如果您需要支持其他索引名称，或者想更改模板中的映射，可以通过将 template 设置为模板文件的路径来指定自定义模板。

将 manage_template 设置为 false 会禁用此功能。如果您需要更好地控制模板创建（例如，根据字段名称动态创建索引），则应将 manage_template 设置为 false，并使用 REST API 手动应用模板。

将一组键值对作为 URL 查询字符串传递。此查询字符串将添加到 hosts 配置中列出的每个主机。如果 hosts 列表包含已具有查询字符串的 URL，则此处指定的查询字符串将被附加。

对于子文档，关联父级的 ID。可以使用 %{foo} 语法进行动态设置。

用于对安全 Elasticsearch 集群进行身份验证的密码

Elasticsearch 服务器所在的 HTTP 路径。如果您必须在代理之后运行 Elasticsearch，该代理会为 Elasticsearch HTTP API 的根路径重新映射，请使用此选项。请注意，如果您在 hosts 字段中使用路径作为 URL 的组成部分，则也不可以设置此字段。这会在启动时引发错误。

设置您希望为事件执行的摄取管道。您还可以在此处使用依赖于事件的配置，例如 pipeline => "%{[@metadata][pipeline]}"。如果值解析为空字符串 ("")，则不会设置 pipeline 参数。

虽然输出会尝试有效地重用连接，但我们有一个最大值。这将设置输出将创建的最大打开连接数。将此值设置得太低可能意味着频繁关闭/打开连接，这是不好的。

虽然输出会尝试有效地重用连接，但每个端点都有一个最大值。这将设置输出将为每个端点创建的最大打开连接数。将此值设置得太低可能意味着频繁关闭/打开连接，这是不好的。

设置转发 HTTP 代理的地址。此设置仅接受 URI 参数，以防止泄漏凭据。空字符串被视为未设置代理。当使用环境变量时，这很有用，例如 proxy => '${LS_PROXY:}'。

在两次复活尝试之间等待的频率（以秒为单位）。复活是检查标记为“关闭”的后端端点是否恢复正常的过程。

设置批量重试之间以秒为单位的初始间隔。每次重试都加倍，直到达到 retry_max_interval

设置批量重试之间以秒为单位的最大间隔。

Elasticsearch 应在内部重试更新/插入文档的次数。

要应用于所有已处理事件的路由覆盖。可以使用 %{foo} 语法进行动态设置。

为脚本更新模式设置脚本名称

示例

    output {
      elasticsearch {
        script => "ctx._source.message = params.event.get('message')"
      }
    }

设置所用脚本的语言。在 Elasticsearch 6.0 及更高版本上使用索引（存储）脚本时，必须将此参数设置为 "" （空字符串）。

定义“script”变量引用的脚本类型

设置传递给脚本的变量名称（脚本更新）

如果启用，脚本将负责创建不存在的文档（脚本更新）

定义您不想记录的 Elasticsearch 错误列表。一个有用的示例是当您想跳过所有 409 错误（即 version_conflict_engine_exception）时。

    output {
      elasticsearch {
        silence_errors_in_log => ["version_conflict_engine_exception"]
      }
    }

此设置会向 Elasticsearch 请求所有集群节点的列表，并将其添加到主机列表。对于 Elasticsearch 5.x 和 6.x，任何具有 http.enabled（默认情况下启用）的节点都将被添加到主机列表，但仅限主节点除外。

在两次嗅探尝试之间等待的时间（以秒为单位）

用于嗅探请求的 HTTP 路径，默认值是通过连接路径值和“_nodes/http”计算得出的，如果设置了 sniffing_path，则它将用作绝对路径，请勿在此处使用完整的 URL，仅使用路径，例如“/sniff/_nodes/http”

用于验证客户端身份的 SSL 证书。此证书应为 OpenSSL 样式的 X.509 证书文件。

用于验证服务器证书的 .cer 或 .pem 文件。

要使用的密码套件列表，按优先级排列。支持的密码套件因 Java 和协议版本而异。

启用与 Elasticsearch 集群的 SSL/TLS 安全通信。如果未指定此项，将使用 hosts 中列出的 URL 中指定的方案，或从 cloud_id 中提取的方案。如果未指定显式协议，则将使用纯 HTTP。

要使用的 SSL 密钥。此密钥必须为 PKCS8 格式且采用 PEM 编码。您可以使用 openssl pkcs8 命令完成转换。例如，将 PEM 编码的 PKCS1 私钥转换为 PEM 编码的非加密 PKCS8 密钥的命令是：

openssl pkcs8 -inform PEM -in path/to/logstash.key -topk8 -nocrypt -outform PEM -out path/to/logstash.pkcs8.key

设置密钥库密码

用于向服务器提供证书的密钥库。它可以是 .jks 或 .p12

密钥库文件的格式。它必须是 jks 或 pkcs12。

建立与 Elasticsearch 集群的连接时要使用的允许的 SSL/TLS 版本列表。

对于 Java 8，'TLSv1.3' 仅在 8u262 (AdoptOpenJDK) 及更高版本中受支持，但需要在 Logstash 中设置 LS_JAVA_OPTS="-Djdk.tls.client.protocols=TLSv1.3" 系统属性。

设置信任库密码

用于验证服务器证书的信任库。它可以是 .jks 或 .p12。

信任库文件的格式。它必须是 jks 或 pkcs12。

定义如何验证 TLS 连接中另一方提供的证书

full 验证服务器证书是否在 not_before 和 not_after 日期之内；链接到受信任的证书颁发机构 (CA)，并具有与证书中的名称匹配的主机名或 IP 地址。

none 不执行证书验证。

如果需要，可以在此处设置您自己的模板的路径。如果未设置，将使用包含的模板。

auto 的默认设置将使用 索引模板 API 来创建索引模板，如果 Elasticsearch 集群正在运行 Elasticsearch 版本 8.0.0 或更高版本，否则将使用 旧版模板 API。

将此标志设置为 legacy 将使用旧版模板 API 创建索引模板。将此标志设置为 composable 将使用索引模板 API 创建索引模板。

此配置选项定义模板在 Elasticsearch 中的命名方式。请注意，如果您使用了模板管理功能并随后更改了此项，则需要手动修剪旧模板，例如：

curl -XDELETE <https://127.0.0.1:9200/_template/OldTemplateName?pretty>

其中 OldTemplateName 是之前的设置。

template_overwrite 选项将始终使用 template 指示的模板或包含的模板覆盖 Elasticsearch 中指示的模板。默认情况下，此选项设置为 false。如果您始终希望与 Logstash 提供的模板保持最新，则此选项对您可能非常有用。同样，如果您有由 puppet 管理的自己的模板文件（例如），并且您希望能够定期更新它，则此选项也可以提供帮助。

请注意，如果您使用的是 Logstash 模板 (logstash) 的自定义版本，则将此项设置为 true 将使 Logstash 覆盖 “logstash” 模板（即删除所有自定义设置）

设置网络操作和发送给 Elasticsearch 的请求的超时时间（以秒为单位）。如果发生超时，将重试该请求。

为更新模式设置 upsert 内容。如果 document_id 不存在，则使用此参数作为 json 字符串创建一个新文档

用于向安全 Elasticsearch 集群进行身份验证的用户名

在检查是否需要保持活动请求的过时连接之前等待的时间。如果经常遇到连接错误，请考虑将此值设置得低于默认值，可能设置为 0。

此客户端基于 Apache Commons。以下是 Apache Commons 文档 对此选项的描述：“定义不活动期间（以毫秒为单位），在此期间，必须在持久连接租借给使用者之前重新验证这些连接。传递给此方法的非正值将禁用连接验证。此检查有助于检测在池中保持不活动状态时已过时（半关闭）的连接。”

用于索引的版本。使用 sprintf 语法（例如 %{my_version}）在此处使用字段值。有关更多信息，请参阅 版本控制支持博客。

用于索引的 version_type。请参阅 版本控制支持博客 和 Elasticsearch 文档中的 版本类型。

用于验证服务器证书的 .cer 或 .pem 文件。

用于向服务器提供证书的密钥库。它可以是 .jks 或 .p12

设置密钥库密码

启用与 Elasticsearch 集群的 SSL/TLS 安全通信。如果未指定此项，将使用 hosts 中列出的 URL 中指定的方案，或从 cloud_id 中提取的方案。如果未指定显式协议，则将使用纯 HTTP。

用于验证服务器证书的选项。禁用此选项会严重损害安全性。有关禁用证书验证的更多信息，请阅读 https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf

用于验证服务器证书的信任存储。它可以是 .jks 或 .p12 文件。请使用 :truststore 或 :cacert。

设置信任库密码

禁用或启用此特定插件实例的指标日志记录。默认情况下，我们会记录所有可以记录的指标，但您可以禁用特定插件的指标收集。

向插件配置添加唯一的 ID。如果未指定 ID，Logstash 将生成一个。强烈建议在您的配置中设置此 ID。当您有两个或多个相同类型的插件时，此功能特别有用。例如，如果您有 2 个 elasticsearch 输出。在这种情况下添加一个命名的 ID 将有助于在使用监控 API 时监控 Logstash。

output {
  elasticsearch {
    id => "my_plugin_id"
  }
}