« 配置 Elastic Cloud 上 Elasticsearch 服务的输出 配置 Logstash 输出 »
Elastic 文档 ›Metricbeat 参考 [8.16] ›配置 Metricbeat ›配置输出

配置 Elasticsearch 输出

编辑

配置 Elasticsearch 输出

编辑

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

示例配置

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

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

通过 elasticsearch 输出将数据发送到安全集群时，Metricbeat 可以使用以下任何身份验证方法：

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

基本身份验证

output.elasticsearch:
  hosts: ["https://myEShost:9200"]
  username: "metricbeat_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"

有关每种身份验证方法的详细信息，请参阅 与 Elasticsearch 的安全通信。

兼容性

编辑

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

可以选择将 Metricbeat 设置为仅连接到版本至少与 Beat 相同的实例。可以通过将 output.elasticsearch.allow_older_versions 设置为 false 来启用此检查。将设置保留为其默认值 true 可以避免 Metricbeat 升级到高于 Elastic Stack 版本的版本后无法连接到 Elasticsearch 的问题。

配置选项

编辑

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

enabled

编辑

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 使用量。

默认值为 1。

escape_html

编辑

配置字符串中 HTML 的转义。设置为 true 以启用转义。

默认值为 false。

worker 或 workers

编辑

每个已配置的主机向 Elasticsearch 发布事件的工作程序数量。这最适合与启用负载均衡模式一起使用。例如：如果您有 2 个主机和 3 个工作程序，则总共启动 6 个工作程序（每个主机 3 个）。

默认值为 1。

loadbalance

编辑

当设置 loadbalance: true 时，Metricbeat 将连接到所有已配置的主机，并通过所有连接并行发送数据。如果连接失败，则数据将发送到其余主机，直到可以重新建立连接为止。只要 Metricbeat 可以连接到至少一个已配置的主机，数据仍然会发送。

当设置 loadbalance: false 时，Metricbeat 将一次向单个主机发送数据。目标主机是从已配置的主机列表中随机选择的，所有数据都发送到该目标，直到连接失败，然后选择新的目标。只要 Metricbeat 可以连接到至少一个已配置的主机，数据仍然会发送。

默认值为 true。

output.elasticsearch:
  hosts: ["localhost:9200", "localhost:9201"]
  loadbalance: true

api_key

编辑

您可以使用 API 密钥来保护与 Elasticsearch 的通信，而不是使用用户名和密码。该值必须是 API 密钥的 ID 和 API 密钥，用冒号分隔：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 在导出 API 的自定义前缀下的 HTTP 反向代理后面侦听的情况很有用。

headers

编辑

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

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

可以通过逗号分隔多个相同的标头名称的标头值。

proxy_disable

编辑

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

proxy_url

编辑

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

proxy_headers

编辑

在 CONNECT 请求期间发送到代理的其他标头。

index

编辑

要将事件写入的索引目标。可以指向 索引、别名 或 数据流。使用每日索引时，这将是索引名称。默认为 "metricbeat-%{[agent.version]}-%{+yyyy.MM.dd}"，例如 "metricbeat-8.16.0-2024-11-19"。如果更改此设置，还需要配置 setup.template.name 和 setup.template.pattern 选项（请参阅 Elasticsearch 索引模板）。

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

启用 索引生命周期管理 (ILM) 时，默认 index 为 "metricbeat-%{[agent.version]}-%{+yyyy.MM.dd}-%{index_num}"，例如 "metricbeat-8.16.0-2024-11-19-000001"。启用 ILM 时，将忽略自定义 index 设置。如果您将事件发送到支持索引生命周期管理的集群，请参阅 索引生命周期管理 (ILM)，了解如何更改索引名称。

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

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

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

使用此配置，所有具有 log_type: normal 的事件都将发送到名为 normal-8.16.0-2024-11-19 的索引，所有具有 log_type: critical 的事件都将发送到名为 critical-8.16.0-2024-11-19 的索引。

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

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

indices

编辑

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

类似于index，定义自定义indices 将禁用索引生命周期管理 (ILM)。

规则设置

index
要使用的索引格式字符串。如果此字符串包含字段引用，例如%{[fields.name]}，则必须存在这些字段，否则规则将失败。
mappings
一个字典，它获取index返回的值并将其映射到一个新名称。
default
如果mappings找不到匹配项，则使用此默认字符串值。
when
必须满足的条件才能执行当前规则。处理器支持的所有条件在此处也受支持。

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

output.elasticsearch:
  hosts: ["https://127.0.0.1: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.16.0-2024-11-19和error-8.16.0-2024-11-19（如果找不到匹配项，则加上默认索引）。

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

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

此配置生成的索引名称为sev1、sev2和sev3。

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

ilm

编辑

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

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

pipeline

编辑

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

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  pipeline: my_pipeline_id

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

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

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

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

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

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

pipelines

编辑

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

规则设置

pipeline
要使用的管道格式字符串。如果此字符串包含字段引用，例如%{[fields.name]}，则必须存在这些字段，否则规则将失败。
mappings
一个字典，它获取pipeline返回的值并将其映射到一个新名称。
default
如果mappings找不到匹配项，则使用此默认字符串值。
when
必须满足的条件才能执行当前规则。处理器支持的所有条件在此处也受支持。

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

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

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

output.elasticsearch:
  hosts: ["https://127.0.0.1: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

编辑

发布失败后重试发布事件的次数。超过指定的重试次数后，事件通常会被丢弃。

将max_retries设置为小于 0 的值，以重试直到所有事件都发布。

默认为 3。

bulk_max_size

编辑

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

事件可以收集到批次中。Metricbeat 将拆分从队列读取的、大于bulk_max_size的批次，将其拆分为多个批次。

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

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

backoff.init

编辑

网络错误后等待重试连接到 Elasticsearch 的秒数。等待backoff.init秒后，Metricbeat 将尝试重新连接。如果尝试失败，则指数级增加回退计时器，直到达到backoff.max。成功连接后，回退计时器将重置。默认为1s。

backoff.max

编辑

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

idle_connection_timeout

编辑

空闲连接在关闭自身之前保持空闲的最大时间量。零表示无限制。格式为 Go 语言持续时间（例如 60s 为 60 秒）。默认为 3s。

timeout

编辑

Elasticsearch 请求的 HTTP 请求超时（秒）。默认为 90。

allow_older_versions

编辑

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

例如，您可以在更新 Elastic Stack 期间禁用此检查，以便可以继续进行数据收集。

ssl

编辑

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

有关详细信息，请参阅与 Elasticsearch 的安全通信指南或SSL 配置参考。

kerberos

编辑

Kerberos 身份验证的配置选项。

有关详细信息，请参阅Kerberos。

non_indexable_policy

编辑

指定 Elasticsearch 集群明确拒绝文档时的行为，例如映射冲突。

drop
编辑

默认行为，当 Elasticsearch 明确拒绝事件时，该事件将被丢弃。

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  non_indexable_policy.drop: ~
dead_letter_index
编辑

此功能处于测试阶段，可能会发生变化。其设计和代码不如正式 GA 功能成熟，按原样提供，不提供任何担保。测试版功能不受正式 GA 功能的支持 SLA 的约束。

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

message
包含原始事件的转义 JSON。
error.type
包含状态代码
error.message
包含 Elasticsearch 返回的状态，描述原因
index
要将拒绝事件发送到的索引。
output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  non_indexable_policy.dead_letter_index:
    index: "my-dead-letter-index"

preset

编辑

要应用于输出配置的性能预设。

output.elasticsearch:
  hosts: ["https://127.0.0.1:9200"]
  preset: balanced

性能预设会根据所需的性能目标应用一组配置覆盖。如果设置了性能预设，则它将覆盖其他配置标志以匹配该预设的推荐设置。有效选项包括：* balanced：一般效率的良好起点 * throughput：适用于高数据量，可能会增加 CPU 和内存需求 * scale：减少大型低吞吐量部署中的环境资源使用 * latency：最大限度地减少新数据在 Elasticsearch 中可见的时间 * custom：直接应用用户配置，无需覆盖

如果未指定，则默认为custom。

预设代表基于预期目标的当前建议；为了更好地适应这些目标，它们的效果可能会在不同版本之间发生变化。目前，预设具有以下效果

preset balanced throughput scale latency

bulk_max_size

1600

1600

1600

50

worker

1

4

1

1

queue.mem.events

3200

12800

3200

4100

queue.mem.flush.min_events

1600

1600

1600

2050

queue.mem.flush.timeout

10s

5s

20s

1s

compression_level

1

1

1

1

idle_connection_timeout

3s

15s

1s

60s

Elasticsearch API

编辑

Metricbeat 将使用 Elasticsearch 的_bulk API，事件按到达发布管道的顺序发送，单个_bulk请求可能包含来自不同输入/模块的事件。临时故障将被重试。

将检查并处理每个事件的状态代码，如下所示：

  • < 300：事件计为events.acked
  • 409（冲突）：事件计为events.duplicates
  • 429（请求过多）：事件计为events.toomany
  • > 399 and < 500：将应用non_indexable_policy。
« 配置 Elastic Cloud 上 Elasticsearch 服务的输出 配置 Logstash 输出 »