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 批量 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 之间的有效负载。但是，如果在 bulk_path 设置中包含了自定义 filter_path 查询参数，则将使用该值。

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

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

有关更多详细信息，请查看 Logstash 到云文档。

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

有关更多详细信息，请查看 Logstash 到云文档。

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，则使用源创建新文档。

索引的文档 ID。对于使用相同 ID 覆盖 Elasticsearch 中的现有条目很有用。

这将设置写入事件的文档类型。通常，您应该尝试仅将类似事件写入相同的类型。字符串扩展 %{foo} 在这里有效。如果您没有为此选项设置值

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

将一组键值对作为发送到每个 Elasticsearch 节点的请求中的标头传递。这些标头将用于任何类型的请求（_批量请求、模板安装、运行状况检查和嗅探）。这些自定义标头将被 compression_level 等设置覆盖。

当后端被标记为关闭时，在后台发送 HEAD 请求的 HTTP 路径，该请求将被发送以查看它是否已恢复，然后再有资格服务请求。如果您有自定义防火墙规则，您可能需要更改此设置

设置远程实例的主机。如果给定一个数组，它将在 hosts 参数中指定的 host 上负载均衡请求。请记住，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 的默认设置将自动启用 索引生命周期管理，否则将禁用它。

将此标志设置为 false 将禁用索引生命周期管理功能，即使 Elasticsearch 集群支持 ILM。将此标志设置为 true 将启用索引生命周期管理功能，如果 Elasticsearch 集群支持它。这需要在低于版本 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，请使用此选项。请注意，如果您在 hosts 字段中使用路径作为 URL 的组件，则可能无法也设置此字段。这将在启动时引发错误

设置要为事件执行的摄取管道。您也可以在此处使用事件相关的配置，例如 pipeline => "%{[@metadata][pipeline]}"。如果值解析为空字符串（""），则不会设置 pipeline 参数。

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

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

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

在复活尝试之间等待多长时间（以秒为单位）。复活是检查标记为 down 的后端端点是否已恢复运行的过程

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

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

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

要应用于所有处理事件的路由覆盖。这可以使用 %{foo} 语法动态实现。

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

示例

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

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

定义“script”变量引用的脚本类型 inline : “script”包含内联脚本 indexed : “script”包含直接索引在 Elasticsearch 中的脚本名称 file : “script”包含存储在 Elasticsearch 配置目录中的脚本名称

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

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

定义您不想记录的 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"
  }
}