Elasticsearch.md

Elasticsearch output 使用Elasticsearch HTTP API将事件直接发送到Elasticsearch。

示例配置：

output.elasticsearch:
  hosts: ["https://myEShost:9200"] 

要启用SSL，请将 https 添加到hosts下定义的所有URL。

通过elasticsearch输出将数据发送到受保护的集群时，FileBeat可以使用以下任何身份验证方法：

• 基本身份验证凭据（用户名和密码）。
• 基于令牌的（API密钥）身份验证。
• 公钥基础设施（PKI）证书。

基本认证：

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  username: "filebeat_writer"
  password: "YOUR_PASSWORD"

API密钥认证：

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA"

PKI证书认证：

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  ssl.certificate: "/etc/pki/client/cert.pem"
  ssl.key: "/etc/pki/client/cert.key"

有关每种身份验证方法的详细信息，请参阅 Secure communication with Elasticsearch。

兼容性

此输出适用于Elasticsearch的所有兼容版本。。请参阅 Elastic支持矩阵。

为了获得最佳体验，FileBeat仅连接到至少与Beat版本相同的实例。可以通过设置output.elasticsearch.allow_older_versions来禁用该检查。

配置选项

您可以在filebeat.yml配置文件的elasticsearch部分指定以下选项：

enabled

布尔，用于启用或禁用输出。如果设置为false，则禁用输出。

默认值为true。

hosts

要连接的Elasticsearch节点列表。事件按循环顺序分发到这些节点。如果一个节点变得不可达，则事件自动发送到另一个节点。每个Elasticsearch节点可以定义为URL或IP:Port。例如：http://192.15.3.2、https://es.found.io:9230 或 192.24.3.2:9300。如果未指定端口，则使用9200。

当节点定义为IP:Port时，scheme 和 path 取自 protocol 和 path 配置选项。

output.elasticsearch:
  hosts: ["10.45.3.2:9220", "10.45.3.1:9230"] 
  protocol: https
  path: /elasticsearch

在上面的示例中，Elasticsearch节点可用于 https://10.45.3.2:9220/elasticsearch 和 https://10.45.3.1:9230/elasticsearch

compression_level

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

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

默认值为0。

escape_html

在字符串中配置超文本标记语言的转义。设置为true以启用转义。

默认值为false。

worker

每个配置的host将事件发布到 Elasticsearch 的 workers 数量。这最好在启用负载平衡模式时使用。例如：如果您有2 hosts 和3 workers，则总共启动6个worker（每个主机3个）。

默认值为 1。

api_key

您可以使用API密钥来保护与Elasticsearch的通信，而不是使用用户名和密码。格式：id:api_key。

有关详细信息，请参阅 使用API密钥授予访问权限。

username

用于连接到Elasticsearch的基本身份验证用户名。

此用户需要将事件发布到Elasticsearch所需的权限。要创建这样的用户，请参阅创建发布用户。

password

连接到Elasticsearch的基本身份验证密码。

parameters

使用索引操作在url中传递的HTTP参数字典。

protocol

可以访问Elasticsearch协议的名称。http或https。默认http。但是，如果您为hosts指定URL，则protocol将被URL覆盖。

path

HTTP API调用前面的HTTP路径前缀。这对于Elasticsearch在HTTP反向代理后面侦听以自定义前缀导出API的情况很有用。

headers

自定义HTTP标头以添加到由Elasticsearch输出创建的每个请求中。示例：

output.elasticsearch.headers:
  X-My-Header: Header contents

可以通过用逗号分隔来为相同的header名称指定多个header值。

proxy_disable

如果设置为true，则忽略所有代理设置，包括HTTP_PROXY和HTTPS_PROXY变量。

proxy_url

连接到Elasticsearch服务器时使用的代理的URL。该值必须是完整的URL。如果未通过配置文件指定值，则使用代理环境变量。有关环境变量的更多信息，请参阅Go文档。

index

The index name to write events to when you’re using daily indices。默认值为 "filebeat-%{[agent.version ]}-%{+ yyyy.MM.dd}"，例如 "filebeat-8.5.1-2022-11-18"。如果更改此设置，还需要配置setup.template.name和setup.template.pattern选项（请参阅Elasticsearch索引模板）。

如果使用预构建的Kibana仪表板，还需要设置setup.dashboards.index选项（请参阅Kibana仪表板）。

启用索引生命周期管理（ILM）时，默认索引为“filebeat-%{[agent.version ]}-%{+ yyyy.MM.dd}-%{index_num}”，例如“filebeat-8.5.1-2022-11-18-000001”。启用ILM时，自定义索引设置将被忽略。如果要将事件发送到支持索引生命周期管理的群集，请参阅索引生命周期管理（ILM）以了解如何更改索引名称。

您可以通过使用格式字符串访问任何事件字段来动态设置索引。例如，此配置使用自定义字段fields.log_type来设置索引：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  index: "%{[fields.log_type]}-%{[agent.version]}-%{+yyyy.MM.dd}" 

我们建议在名称中包含agent.version，以避免升级时出现映射问题。

使用此配置，所有具有log_type: normal的事件都被发送到名为normal-8.5.1-2022-11-18的索引，所有具有log_type: critical的事件都被发送到名为critical-8.5.1-2022-11-18的索引。

若要了解如何向事件添加自定义字段，请参阅fields选项。

有关动态设置索引的其他方法，请参阅indices设置。

indices

索引选择器规则数组。每个规则指定用于匹配规则的事件的索引。在发布过程中，FileBeat使用数组中的第一个匹配规则。规则可以包含条件、基于字符串的格式字段和名称映射。如果缺少indices设置或没有规则匹配，则使用index设置。

与index类似，定义自定义indices将禁用 索引生命周期管理（ILM）。

规则设置：

index

要使用的索引格式字符串。如果此字符串包含字段引用，例如%{[fields.name]}，则这些字段必须存在，否则规则失败。

mappings

接受index返回的值并将其映射到新名称的字典。

default

如果mappings未找到匹配项，则使用的默认字符串值。

when

必须成功才能执行当前规则的条件。这里也支持处理器支持的所有条件。

以下示例根据message字段是否包含指定字符串来设置索引：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  indices:
    - index: "warning-%{[agent.version]}-%{+yyyy.MM.dd}"
      when.contains:
        message: "WARN"
    - index: "error-%{[agent.version]}-%{+yyyy.MM.dd}"
      when.contains:
        message: "ERR"

此配置会产生名为warning-8.5.1-2022-11-18和error-8.5.1-2022-11-18的索引（如果未找到匹配项，则加上默认索引）。

以下示例通过获取索引格式字符串返回的名称并将其映射到用于索引的新名称来设置索引：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  indices:
    - index: "%{[fields.log_type]}"
      mappings:
        critical: "sev1"
        normal: "sev2"
      default: "sev3"

索引默认为sev3，当log_type是“critical”则索引为sev1，当log_type为”normal“则索引为sev2。

mappings 设置简化了配置，但仅限于字符串值。您不能在映射对中指定格式字符串。

ilm

索引生命周期管理的配置选项。

有关详细信息，请参阅索引生命周期管理（ILM）。

pipeline

一个格式字符串值，指定要将事件写入的摄取管道。

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  pipeline: my_pipeline_id

有关详细信息，请参阅使用摄取管道解析数据。

您可以通过使用格式字符串访问任何事件字段来动态设置摄取管道。例如，此配置使用自定义字段fields.log_type为每个事件设置管道：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  pipeline: "%{[fields.log_type]}_pipeline"

使用此配置，所有具有log_type：normal的事件都将发送到名为normal_pipeline的管道，所有具有log_type：critical的事件都将发送到名为critical_pipeline的管道。

若要了解如何向事件添加自定义字段，请参阅 fields 选项。

有关动态设置摄取管道的其他方法，请参阅管道设置。

pipelines

管道选择器规则数组。每个规则指定用于匹配规则的事件的摄取管道。在发布过程中，FileBeat使用数组中的第一个匹配规则。规则可以包含条件、基于字符串的格式字段和名称映射。如果pipelines设置缺失或没有规则匹配，则使用pipeline设置。

规则设置：

pipeline

要使用的管道格式字符串。如果此字符串包含字段引用，例如%{[fields.name]}，则这些字段必须存在，否则规则失败。

mappings

获取pipeline返回的值并将其映射到新名称的字典。

default

如果mappings未找到匹配项，则使用的默认字符串值。

when

必须成功才能执行当前规则的条件。这里也支持处理器支持的所有条件。

以下示例根据message字段是否包含指定字符串将事件发送到特定管道：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  pipelines:
    - pipeline: "warning_pipeline"
      when.contains:
        message: "WARN"
    - pipeline: "error_pipeline"
      when.contains:
        message: "ERR"

以下示例通过获取pipeline格式字符串返回的名称并将其映射到用于管道的新名称来设置管道：

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  pipelines:
    - pipeline: "%{[fields.log_type]}"
      mappings:
        critical: "sev1_pipeline"
        normal: "sev2_pipeline"
      default: "sev3_pipeline"

使用此配置，所有具有log_type: critical的事件都发送到sev1_pipeline，所有具有log_type: normal的事件都发送到sev2_pipeline，所有其他事件都发送到sev3_pipeline。

有关摄取管道的详细信息，请参阅使用摄取管道解析数据。

max_retries

重试次数，默认3次，超过3次后，当前事件将被丢弃

bulk_max_size

单个Elasticsearch批量API索引请求中要批量处理的最大事件数。默认值为50。

事件可以被收集成批次。FileBeat会将大于bulk_max_size的批次拆分为多个批次。

指定较大的批量大小可以通过降低发送事件的开销来提高性能。然而，大批量大小也会增加处理时间，这可能会导致API错误、终止连接、超时发布请求，并最终降低吞吐量。

将bulk_max_size设置为小于或等于0的值将禁用批次的拆分。禁用拆分时，队列将决定批次中要包含的事件数量。

backoff.init

网络错误后尝试重新连接到Elasticsearch之前要等待的秒数。等待backoff.init秒后，FileBeat尝试重新连接。如果尝试失败，退避计时器将按指数增加，最高可达backoff.max。连接成功后，退避计时器将重置。默认值为1s。

backoff.max

网络错误后尝试连接到Elasticsearch之前等待的最大秒数。默认值为60s。

timeout

Elasticsearch请求的超文本传输协议请求超时（以秒为单位）。默认值为90。

allow_older_versions

默认情况下，FileBeat期望Elasticsearch实例使用相同或更新的版本以提供最佳体验。我们建议您连接到相同的版本，以确保FileBeat使用的所有功能在您的Elasticsearch实例中都可用。

您可以禁用检查，例如在更新Elastic Stack期间，这样数据采集就可以继续。

ssl

SSL参数的配置选项，例如用于基于HTTPS的连接的证书颁发机构。如果缺少ssl部分，则主机CA用于与Elasticsearch的HTTPS连接。

有关更多信息，请参阅Elasticsearch安全通信指南或SSL配置参考。

kerberos

Kerberos身份验证的配置选项。

See Kerberos for more information.

non_indexable_policy

指定elasticsearch集群显式拒绝 documents 时的行为，例如在映射冲突时。

drop

默认行为，当事件被elasticsearch显式拒绝时，它会被删除。

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  non_indexable_policy.drop: ~

dead_letter_index

此功能处于测试阶段，可能会发生变化。设计和代码不如官方GA功能成熟，并且按原样提供，没有保证。测试功能不受官方GA功能支持SLA的约束。

在显式拒绝时，此策略将在下一批中重试事件。但是，目标索引将更改为指定的索引。此外，事件的结构将更改为以下字段：

message

包含原始事件的转义json。

error.type

包含状态码

error.message

包含elasticsearch返回的状态，描述原因

index

要将拒绝的事件发送到的索引。

output.elasticsearch:
  hosts: ["http://localhost:9200"]
  non_indexable_policy.dead_letter_index:
    index: "my-dead-letter-index"